lastlight 0.1.15 → 0.2.1

package/workflows/pr-comment.yaml

@@ -0,0 +1,16 @@
+kind: comment
+name: pr-comment
+description: |
+  Answer a maintainer's question about an open PR with concrete, code-cited
+  evidence. The PR-side counterpart to `issue-comment` — distinguished
+  because PR questions need the diff and a higher file-read cap.
+
+  Triggered by:
+    - issue_comment.created webhook on a PR (when classifier returns a
+      non-build intent and prNumber is set)
+
+phases:
+  - name: respond
+    label: Respond
+    skill: pr-comment
+    model: "{{models.comment}}"

package/workflows/pr-fix.yaml

@@ -2,11 +2,14 @@ kind: pr-fix
 name: pr-fix
 description: "Lightweight PR fix — no architect/reviewer, just fix and push"
 trigger: pr-fix
+# Single in-place task-list comment/message instead of a comment per phase.
+status_checklist: true
 
 phases:
   - name: fix
     label: Fix
     prompt: prompts/pr-fix.md
+    skill: building
     model: "{{models.pr-fix}}"
     messages:
       on_start: "On it — fixing PR #{{prNumber}}..."

package/workflows/pr-review.yaml

@@ -13,5 +13,8 @@ description: |
 phases:
   - name: review
     label: Review
-    skill: pr-review
+    # pr-review: the PR procedure (primary). building: install + test gate.
+    # code-review: the finding-tier + what-to-check rubric.
+    skills: [pr-review, building, code-review]
     model: "{{models.review}}"
+    variant: "{{variants.review}}"

package/workflows/prompts/answer.md

@@ -0,0 +1,67 @@
+You are answering a **question** — the user wants information, an explanation,
+or a comparison, not a code change. Read the `issue-answer` skill for the full
+procedure and rules, then follow it. This prompt gives you the specific question
+and how your answer is delivered.
+
+## The question
+
+{{#if issueTitle}}**Issue title:** {{issueTitle}}{{/if}}
+{{#if issueBody}}
+**Issue body:**
+{{issueBody}}
+{{/if}}
+{{#if commentBody}}
+**Question:**
+{{commentBody}}
+{{/if}}
+
+Target repo: **{{owner}}/{{repo}}**
+{{#if issueNumber}}Originating GitHub issue: **#{{issueNumber}}**{{/if}}
+
+## Workspace
+
+The repo is (or will be) in a `{{repo}}/` subdirectory under your cwd:
+
+```
+ls -la
+```
+
+If you see `{{repo}}/.git/`, the harness pre-cloned it — `cd {{repo}}`.
+Otherwise `git clone https://github.com/{{owner}}/{{repo}}.git {{repo}}` and
+`cd` in. Read what the question needs (`CONTEXT.md`, `README`, `docs/`,
+`spec/`, code) — don't survey the whole tree. Use the `web_search` /
+`web_fetch` tools for anything outside this repo (other tools, frameworks,
+"X vs Y" comparisons); cite what you use.
+
+## How your answer is delivered — read carefully
+
+Your **final message is the answer**, and the harness posts it for you:
+{{#if issueNumber}}
+- as a comment on issue #{{issueNumber}}.
+{{/if}}
+{{#if !issueNumber}}
+- back into the Slack thread this question came from.
+{{/if}}
+
+So make your final message the complete, self-contained answer in clean
+markdown — no "here's what I'll do" preamble, no meta-commentary.
+
+**Converge — don't get cut off.** Your tool budget is bounded. The moment you
+think "I have enough" or "let me just confirm one more thing", stop researching
+and write the answer in that same turn — do **not** fire another tool call
+first. A reply truncated mid-research is worse than one that omits a minor
+detail; flag anything unverified as unverified rather than chasing it with your
+last turn.
+
+**Do NOT post the answer yourself** (no `github_add_issue_comment`) — that would
+double-post. The only GitHub write you make is the label:
+
+{{#if issueNumber}}
+- Apply the `question` label to issue #{{issueNumber}} with `github_add_labels`
+  (create it first with `github_create_label`, color `d876e3`; ignore a 422).
+  Leave the issue open.
+{{/if}}
+{{#if !issueNumber}}
+- This is a Slack-initiated question — there is no issue to label. Just produce
+  the answer.
+{{/if}}

package/workflows/prompts/architect.md

@@ -1,9 +1,11 @@
 You are the ARCHITECT. Analyze the codebase and produce an implementation plan.
 
-SETUP (git is pre-configured, you are in a sandbox workspace):
-1. git clone --branch {{branch}} https://github.com/{{owner}}/{{repo}}.git && cd {{repo}}
-2. Read CLAUDE.md and AGENTS.md if they exist
-3. Read {{issueDir}}/guardrails-report.md for pre-flight results
+You are already inside the {{repo}} repo at branch {{branch}} — the harness
+pre-cloned it and your cwd is the repo root. Git is configured.
+
+Before planning:
+1. Read CLAUDE.md (and CONTRIBUTING.md if present) for project-specific guidance.
+2. Read {{issueDir}}/guardrails-report.md for the test/lint/typecheck commands.
 
 CONTEXT:
 {{contextSnapshot}}
@@ -11,9 +13,24 @@ CONTEXT:
 OUTPUT — write the plan to {{issueDir}}/architect-plan.md:
 - Problem Statement (2-5 sentences with file:line references)
 - Summary of what needs to change
-- Files to modify (with line numbers and what to change)
+- Files to modify — an EXHAUSTIVE manifest the executor implements verbatim:
+  - List EVERY file to change, with the exact path, line/symbol anchor, and what
+    to change. The executor should not need to go hunting for files.
+  - Enumerate ALL members of any multi-file group. If a change touches one
+    member of a set, glob/`ls` the set and list them ALL — e.g. every i18n
+    locale under the locales dir, every adapter/provider variant, every test
+    file for the touched module. Name the exact keys/identifiers to add (e.g.
+    the precise i18n keys). Missing a sibling here forces the executor to
+    rediscover it mid-implementation.
+- Commands — copy the exact test / lint / typecheck commands from
+  guardrails-report.md into the plan so the executor uses them directly.
 - Implementation approach (step-by-step)
 - Risks and edge cases
+  - For every input the design does NOT fully support, specify **warn-and-skip**
+    or **warn-and-surface** behaviour explicitly. A silent default, a silently
+    skipped case, or a dropped output is a correctness bug — never plan for one.
+    If an input can't be handled, the plan must say how the user is told (a
+    warning, a surfaced error), not let it disappear.
 - Test strategy
 - Estimated complexity: simple / medium / complex
 
@@ -21,7 +38,7 @@ AFTER WRITING:
 1. mkdir -p {{issueDir}}
 2. Write architect-plan.md
 3. Write status.md with current_phase: architect
-4. git add .lastlight/ && git commit -m "docs: architect plan for #{{issueNumber}}"
-5. git push -u origin HEAD
+{{#if !externalizeArtifacts}}4. git add .lastlight/ && git commit -m "docs: architect plan for #{{issueNumber}}"
+5. git push -u origin HEAD{{/if}}{{#if externalizeArtifacts}}4. Do NOT git add or commit {{issueDir}}/ — the harness persists it to the Last Light server automatically.{{/if}}
 
 OUTPUT: The branch name and a brief summary (3-5 lines).

package/workflows/prompts/demo.md

@@ -0,0 +1,100 @@
+You are recording a short **demo video** of a PR or feature — driving the
+repo's web UI in a **real headless browser**, screen-recording the session, and
+compositing a titled mp4. Read the `demo` skill for the director procedure and
+the `compose-demo.sh` wrapper, the `browser-qa` skill for the driver contract,
+and the `building` skill for install/run — then follow them.
+
+**Stay in the browser.** Your deliverable is a *moving* demonstration of
+behaviour, not a code walkthrough. Don't quote or analyse source files — show
+what the running app does.
+
+## What to demo
+
+{{#if commentBody}}
+**Request / notes:**
+{{commentBody}}
+{{/if}}
+{{#if issueTitle}}**Issue/PR title:** {{issueTitle}}{{/if}}
+{{#if issueBody}}
+**Issue/PR body:**
+{{issueBody}}
+{{/if}}
+
+Target repo: **{{owner}}/{{repo}}** at branch {{branch}}
+{{#if issueNumber}}Target issue/PR: **#{{issueNumber}}**{{/if}}
+
+Read the PR (description, diff, linked issue) from the context above. Decide the
+single thing the video must prove — the moment that only happens if the change
+works as claimed — and whether the story is a `single` walkthrough (default) or a
+`side-by-side` before/after comparison (only for a genuine regression/refactor).
+
+## First: confirm the browser + ffmpeg are available
+
+Run the driver's probe before anything else (the `browser-qa` skill is staged
+into this phase's bundle — find its absolute path from the available-skills
+catalogue):
+
+```
+node <browser-qa skill dir>/scripts/agent-browser.mjs doctor
+```
+
+If `doctor` exits non-zero, the toolchain isn't present: say so plainly and
+stop — **do not fake a recording.** This phase only runs on the docker QA image,
+so `doctor` should pass.
+
+## Workspace + run the app
+
+You are already inside the **{{repo}}** repo at branch {{branch}} — the harness
+pre-cloned it and your cwd is the repo root (no `cd`). Follow the `building`
+skill to install dependencies and start the dev-server in the background; poll
+with `curl` until it answers on `localhost:<port>`. For a before/after demo,
+run each branch in turn and record the same scripted interaction against each.
+
+## Capture and compose
+
+Author a `flow.json` (shape in the `browser-qa` skill) that scripts the
+interaction like a director — record the baseline first, hold after state
+changes, verify between steps. Record with `--record-dir`:
+
+```
+node <browser-qa skill dir>/scripts/agent-browser.mjs run flow.json \
+  --base-url http://localhost:<port> --record-dir /tmp/demo-cap
+```
+
+Then composite the raw webm into the final mp4 with the `demo` skill's wrapper,
+writing it into **`{{issueDir}}/demo.mp4`** (the harness harvests that dir):
+
+```
+<demo skill dir>/scripts/compose-demo.sh \
+  --output {{issueDir}}/demo.mp4 --title "<PR # — what it does>" \
+  --subtitle "<one line>" --layout single --speed 1.5 --target-size-mb 5 \
+  /tmp/demo-cap/session.webm
+```
+
+Self-check the result with `ffprobe` (the wrapper prints a summary): resolution
+sane, duration watchable (~15–90s), and **size ≤ 5 MB** so GitHub embeds it. If
+it's over, re-run with a lower `--target-size-mb` or a higher `--speed`.
+
+## How your report is delivered — read carefully
+
+Your **final message is the report**, and the harness posts it for you{{#if issueNumber}} as a
+comment on **#{{issueNumber}}**{{/if}}{{#if !issueNumber}} back into the thread this request came from{{/if}}.
+Use the `demo` skill's report shape — a one-line environment summary, a sentence
+on what the video shows and the moment to watch, the video, and a one-line
+"not covered". **Keep it tight.**
+
+**Embed the video inline so it plays in the comment.**
+{{#if artifactBaseUrl}}Your `{{issueDir}}/demo.mp4` is served publicly at
+`{{artifactBaseUrl}}/demo.mp4`. Include a raw HTML video tag on its own line —
+`<video src="{{artifactBaseUrl}}/demo.mp4" controls></video>` — plus a plain
+link beneath it as a fallback: `[demo.mp4]({{artifactBaseUrl}}/demo.mp4)`. GitHub
+renders `<video>` in comments. Do **NOT** wrap the tag in backticks or a code
+fence (inside a code span it shows as literal text instead of playing).{{/if}}{{#if !artifactBaseUrl}}No
+public URL is configured, so reference the video by filename (`demo.mp4`) and
+note it's in the run's Artifacts view.{{/if}}
+
+**Do NOT post it yourself** with `github_add_issue_comment` — that would
+double-post. Never stage or fabricate a result the feature didn't produce; if
+something doesn't work, the honest demo shows it. If the video couldn't be
+recorded or persisted (no server-mode build assets), say so plainly and describe
+what you observed instead of pretending a clip exists.

package/workflows/prompts/executor.md

@@ -1,27 +1,36 @@
 You are the EXECUTOR. Implement precisely what the architect's plan requires.
 
-SETUP (git is pre-configured, you are in a sandbox workspace):
-1. git clone --branch {{branch}} https://github.com/{{owner}}/{{repo}}.git && cd {{repo}}
-2. Read {{issueDir}}/architect-plan.md
-
-EXECUTION:
-- Follow TDD: write failing test first, then implement, then verify
-- Run tests and verify they pass
-
-BEFORE COMMITTING — ALL GUARDRAILS MUST PASS:
-1. Read {{issueDir}}/guardrails-report.md to find the exact commands
-2. Run the test command and verify ALL tests pass (zero failures)
-3. Run the lint command (if present) and fix ALL lint errors
-4. Run the typecheck command (if present) and fix ALL type errors
-5. If any guardrail fails, fix the issue and re-run until clean
-DO NOT commit or claim done until tests, lint, and typecheck all pass.
-
-AFTER ALL GUARDRAILS PASS:
+You are already inside the {{repo}} repo at branch {{branch}} — the harness
+pre-cloned it and your cwd is the repo root. Git is configured.
+
+Start by reading {{issueDir}}/architect-plan.md.
+
+WORK FROM THE PLAN — it contains an exhaustive file manifest and the exact
+commands:
+- Implement the plan's file manifest directly. Read a file only immediately
+  before you edit it; do NOT re-explore areas the plan already mapped.
+- Use grep/find only to fill genuine gaps the plan didn't cover (if the plan
+  is missing a sibling file, fix it there and proceed).
+- Use the test/lint/typecheck commands the plan copied from the guardrails
+  report — no need to re-open guardrails-report.md unless the plan omitted them.
+
+Follow the **building** skill for the mechanics: install dependencies first,
+write the failing test before implementing (TDD), and run the full
+test/lint/typecheck gate once before committing — all of it must pass before you
+commit or claim done.
+
+Before committing, also honour the building skill's **decomposition budget** and
+**type-safety** rules: keep functions under ~15 cyclomatic complexity (a
+function that parses, validates, and emits is three functions — extract helpers),
+and never use `as any` or other compiler-silencing assertions to pass the gate or
+to skip a validator the same code defines. If the repo's only test path needs an
+unavailable external service, add a runnable unit/CLI test with in-memory
+fixtures rather than declaring the change unverified.
+
+AFTER THE GATE PASSES:
 1. Write {{issueDir}}/executor-summary.md:
    - What was done, files changed
-   - Test results (paste actual output)
-   - Lint results (paste actual output)
-   - Typecheck results (paste actual output)
+   - Test / lint / typecheck results (paste actual output)
    - Any deviations from the plan, known issues
 2. Update {{issueDir}}/status.md: current_phase = executor
 3. git add -A && git commit -m "feat: implement #{{issueNumber}}

package/workflows/prompts/explore-ask.md

@@ -2,11 +2,12 @@ You are running a socratic questioning loop to help a maintainer shape a
 half-formed idea into a detailed spec. This is iteration {{iteration}} of
 {{maxIterations}}.
 
-The **{{owner}}/{{repo}}** repo is cloned in your workspace.
+The **{{owner}}/{{repo}}** repo is checked out at `{{repo}}/` (a
+subdirectory of your cwd) — the previous read phase ensured it.
 
-**Important paths** (all absolute — use these exactly):
-- Repo root: `/home/agent/workspace/{{repo}}`
-- Context doc: `/home/agent/workspace/{{repo}}/{{issueDir}}/explore-context.md`
+**Important paths** (relative to the workspace cwd):
+- Repo root: `{{repo}}/` (cd into it to use git)
+- Context doc: `{{issueDir}}/explore-context.md`
 
 Start by reading the context doc for architecture, key code excerpts, and
 existing patterns. Only read additional source files if the context doc
@@ -34,24 +35,46 @@ good spec:
 
 ### If you DON'T have enough signal yet
 
-Read relevant code if it helps sharpen your questions. Then write a short
-message to the user asking **1 to 3 focused clarifying questions**. Keep it
-conversational — the user will reply in the same thread with their answers.
-Good questions:
-
-- pin down scope ("is this only for X, or also for Y?")
-- surface hidden constraints ("does this need to be backwards-compatible
-  with the existing Z?")
-- flush out users / success criteria ("who would use this, and what
-  would make them say 'this worked'?")
-- reference specific code you found ("I see `FooService` handles this
-  today — should the new feature extend it or replace it?")
+Walk down the design tree one branch at a time, resolving dependencies
+between decisions in order — answering an upstream decision often changes
+what the downstream questions even are.
+
+**First, try to answer the question yourself.** If reading the code would
+settle it, read the code instead of asking. Only put a question to the user
+when the codebase genuinely can't decide it.
+
+**Then, of the questions that remain, only ASK about the high-stakes ones**
+— decisions where guessing wrong would be costly or hard to reverse, or
+where the design genuinely forks. **Low-stakes decisions you decide
+yourself**: pick the sensible default (usually "follow the existing
+pattern"), and record it in `{{issueDir}}/explore-context.md` under a
+`## Decisions made during exploration` section (create it if absent), as
+`<decision> → <what you chose> (<one-line why>)`. The user can override
+any of these later; surfacing them in the spec is enough.
+
+When you do ask, ask **one primary question per turn**, and **always give
+your recommended answer** with a one-line rationale grounded in the code
+you read. If a second question is trivially coupled to the first (you can't
+sensibly answer one without the other), you may tack it on as a short
+follow-up — but never a flat list of unrelated questions. Keep it
+conversational; the user replies in the same thread.
+
+Shape of a good turn:
+
+> I see `FooService` already handles this today. I'd **extend** it rather
+> than add a parallel service — it already owns the auth path. Sound right?
+> ↳ If we extend, I'd reuse its existing 5-min cache rather than add a new
+> one (assuming that's fine).
+
+Good questions pin down scope ("only X, or also Y?"), surface hidden
+constraints ("must this stay backwards-compatible with Z?"), flush out
+users / success criteria ("who uses this, and what makes them say it
+worked?"), and reference specific code you found.
 
 If you discover new relevant code, **append it to
-`/home/agent/workspace/{{repo}}/{{issueDir}}/explore-context.md`** so the
-synthesize phase has it too.
+`{{issueDir}}/explore-context.md`** so the synthesize phase has it too.
 
-**Do NOT output the word READY** on this path. Just the questions.
+**Do NOT output the word READY** on this path. Just the question.
 
 ### If you DO have enough signal
 
@@ -63,8 +86,14 @@ advances to the synthesis phase.
 ## Rules
 
 - Never ask the same question twice — check the accumulated Q&A first.
-- Never ask more than 3 questions per iteration.
-- If the user says "we're done" or "just write it up" in their most
-  recent answer, output READY immediately.
+- Ask **one** primary question per turn (plus an optional tightly-coupled
+  follow-up). Never dump a list of unrelated questions.
+- Every question carries your recommended answer — never ask open-endedly
+  without saying what you'd do.
+- Prefer deciding low-stakes items yourself (recorded in the context doc)
+  over asking. Only escalate genuinely high-stakes / forking decisions.
+- If the user says "we're done", "just write it up", or "your
+  recommendations look good" in their most recent answer, output READY
+  immediately.
 - Don't preamble or recap — the user can see the thread already.
 - Use the cloned repo to make your questions specific and grounded.

package/workflows/prompts/explore-publish.md

@@ -3,14 +3,14 @@ You are publishing an approved spec that the previous phase wrote to
 
 ## Your task
 
-1. Read the spec file at `/home/agent/workspace/{{repo}}/{{issueDir}}/explore-spec.md`.
+1. Read the spec file at `{{issueDir}}/explore-spec.md` (relative to the cwd).
 2. Decide the destination based on where this explore was triggered from:
 
 ### GitHub-originated (triggered by a comment on an existing issue)
 
 If `{{issueNumber}}` is set and non-zero (and not a Slack-originated run),
 post the spec as a **comment on issue #{{issueNumber}}** in
-`{{owner}}/{{repo}}` using the GitHub MCP `create_issue_comment` tool.
+`{{owner}}/{{repo}}` using the `github_add_issue_comment` MCP tool.
 
 ### Slack-originated (triggered in a Slack thread)
 

package/workflows/prompts/explore-read.md

@@ -3,16 +3,27 @@ any clarifying questions, you need to clone the target repo, explore the
 relevant code, and write a detailed context document that all subsequent
 phases will reference.
 
-## Step 1 — Clone the repo
+## Step 1 — Prepare the workspace
 
-Clone **{{owner}}/{{repo}}** into your workspace and cd into it:
+The repo lives (or will live) in a `{{repo}}/` subdirectory under your
+cwd. Check first:
 
 ```
-git clone https://github.com/{{owner}}/{{repo}}.git && cd {{repo}}
+ls -la
 ```
 
-(Git credentials are already configured — just run the clone.)
-All subsequent commands and file paths are relative to `{{repo}}/`.
+- If you see `{{repo}}/.git/` already, the harness pre-cloned it.
+  `cd {{repo}}` and continue.
+- Otherwise clone it into a `{{repo}}/` subdirectory and cd in:
+
+  ```
+  git clone https://github.com/{{owner}}/{{repo}}.git {{repo}}
+  cd {{repo}}
+  ```
+
+  Git credentials are already configured.
+
+All subsequent file paths in this prompt are relative to the cwd.
 
 {{#if issueNumber}}
 ## Step 2 — Read the issue
@@ -52,15 +63,18 @@ understand everything relevant to the idea. Look at:
 
 ## Step 4 — Write the context document
 
-First create the working directory:
+First create the scratch directory at the WORKSPACE root (alongside
+`{{repo}}/`, not inside it):
 
 ```
-mkdir -p /home/agent/workspace/{{repo}}/{{issueDir}}
+mkdir -p ../{{issueDir}}    # if you're inside the {{repo}}/ subdir
+# OR, if you cd'd back out:
+mkdir -p {{issueDir}}
 ```
 
-Then write a detailed context file to
-**`/home/agent/workspace/{{repo}}/{{issueDir}}/explore-context.md`**
-that captures everything you found. This file is the primary reference for
+Then write a detailed context file to **`{{issueDir}}/explore-context.md`**
+relative to the workspace root (i.e. `../{{issueDir}}/explore-context.md`
+when you're inside the repo subdir). This file is the primary reference for
 all subsequent phases — they should rarely need to re-explore the codebase.
 
 Structure it as:

package/workflows/prompts/explore-synthesize.md

@@ -1,12 +1,13 @@
 You are writing the detailed spec for an idea that's been shaped through a
 socratic Q&A loop with a maintainer.
 
-The **{{owner}}/{{repo}}** repo is cloned in your workspace.
+The **{{owner}}/{{repo}}** repo is checked out at `{{repo}}/` (a
+subdirectory of your cwd).
 
-**Important paths** (all absolute — use these exactly):
-- Repo root: `/home/agent/workspace/{{repo}}`
-- Context doc: `/home/agent/workspace/{{repo}}/{{issueDir}}/explore-context.md`
-- Spec output: `/home/agent/workspace/{{repo}}/{{issueDir}}/explore-spec.md`
+**Important paths** (relative to the workspace cwd):
+- Repo root: `{{repo}}/` (cd into it to use git)
+- Context doc: `{{issueDir}}/explore-context.md`
+- Spec output: `{{issueDir}}/explore-spec.md`
 
 Start by reading the context doc — it contains the architecture, key code
 excerpts, and existing patterns captured during the initial read and
@@ -28,8 +29,7 @@ context doc doesn't cover what you need.
 Read the relevant parts of the codebase to ground the spec in reality.
 Then produce a detailed spec document. The structure below is the target —
 hit every heading, even if a section is "none" or "to be decided". Write it
-to `/home/agent/workspace/{{repo}}/{{issueDir}}/explore-spec.md` using the
-Write tool.
+to `{{issueDir}}/explore-spec.md` using the Write tool.
 
 ```
 # <short title summarizing the idea>
@@ -57,6 +57,13 @@ patterns from the codebase. Break into subsections if useful.>
 |------|--------|
 | path/to/file | what changes |
 
+## Decisions made during exploration
+<Low-stakes decisions the agent resolved itself during the Q&A loop rather
+than asking — pull these from the `## Decisions made during exploration`
+section of the context doc. Format as `<decision> → <choice> (<why>)`. The
+maintainer can override any of these. Omit the heading only if there were
+none.>
+
 ## Acceptance criteria
 - <observable outcome 1>
 - <observable outcome 2>
@@ -70,7 +77,7 @@ patterns from the codebase. Break into subsections if useful.>
 
 ## Rules
 
-- Write the file to `/home/agent/workspace/{{repo}}/{{issueDir}}/explore-spec.md`
+- Write the file to `{{issueDir}}/explore-spec.md`
   — don't inline it in your reply.
 - Reference actual code paths from the repo, not hypothetical ones.
 - After writing the file, output a short summary (3-6 lines) saying what

package/workflows/prompts/fix.md

@@ -1,17 +1,16 @@
 You are the EXECUTOR (fix cycle {{fixCycle}}). Fix ONLY the issues reported by the reviewer.
 
-SETUP (git is pre-configured, you are in a sandbox workspace):
-1. git clone --branch {{branch}} https://github.com/{{owner}}/{{repo}}.git && cd {{repo}}
-2. Read {{issueDir}}/reviewer-verdict.md — fix ONLY these issues
-3. Read {{issueDir}}/guardrails-report.md for the test/lint/typecheck commands
+You are already inside the {{repo}} repo at branch {{branch}} — the harness
+pre-cloned it and your cwd is the repo root. Git is configured.
 
-BEFORE COMMITTING — ALL GUARDRAILS MUST PASS:
-1. Run the test command and verify ALL tests pass (zero failures)
-2. Run the lint command (if present) and fix ALL lint errors
-3. Run the typecheck command (if present) and fix ALL type errors
-DO NOT commit until tests, lint, and typecheck all pass.
+Start by reading {{issueDir}}/reviewer-verdict.md — fix ONLY those issues. The
+test/lint/typecheck commands are in {{issueDir}}/guardrails-report.md (and the
+architect plan).
 
-AFTER ALL GUARDRAILS PASS:
+Follow the **building** skill: run the full test/lint/typecheck gate once before
+committing — all of it must pass before you commit.
+
+AFTER THE GATE PASSES:
 1. APPEND to {{issueDir}}/executor-summary.md under heading "## Fix Cycle {{fixCycle}}" (what was fixed, test/lint/typecheck results)
 2. Update status.md: current_phase = fix_loop_{{fixCycle}}
 3. git add -A && git commit -m "fix: address review feedback for #{{issueNumber}} (cycle {{fixCycle}})" && git push origin HEAD

package/workflows/prompts/guardrails.md

@@ -1,9 +1,11 @@
 You are running a PRE-FLIGHT GUARDRAILS CHECK before implementation work begins.
 
-SETUP (git is pre-configured, you are in a sandbox workspace):
-1. Try: git clone --branch {{branch}} https://github.com/{{owner}}/{{repo}}.git && cd {{repo}}
-   If the branch doesn't exist yet: git clone https://github.com/{{owner}}/{{repo}}.git && cd {{repo}} && git checkout -b {{branch}}
-2. Read CLAUDE.md and AGENTS.md if they exist
+You are already inside the {{repo}} repo at branch {{branch}} — the harness
+pre-cloned it and your cwd is the repo root. Read CLAUDE.md (and
+CONTRIBUTING.md if present) for project-specific guidance.
+
+THE ISSUE THIS BUILD WILL IMPLEMENT (use it to judge the escape hatch below):
+{{contextSnapshot}}
 
 SKIP CHECK — if {{issueDir}}/status.md already exists and contains
 guardrails_status: READY, output "READY — guardrails already verified" and stop.
@@ -25,16 +27,32 @@ AFTER CHECKING:
 1. mkdir -p {{issueDir}}
 2. Write {{issueDir}}/guardrails-report.md with the status of each check
 3. Write {{issueDir}}/status.md with current_phase: guardrails AND guardrails_status: READY or BLOCKED
-4. git add .lastlight/ && git commit -m "docs: guardrails check for #{{issueNumber}}"
-5. git push -u origin HEAD
+{{#if !externalizeArtifacts}}4. git add .lastlight/ && git commit -m "docs: guardrails check for #{{issueNumber}}"
+5. git push -u origin HEAD{{/if}}{{#if externalizeArtifacts}}4. Do NOT git add or commit {{issueDir}}/ — the harness persists it to the Last Light server automatically.{{/if}}
+
+ESCAPE HATCH — bootstrap tasks (CHECK THIS FIRST):
+If THE ISSUE ABOVE is itself asking to ADD the tooling you're checking for —
+set up tests / a test harness, linting, type-checking, CI, an AGENTS.md, etc. —
+then missing tooling is the expected STARTING state, not a blocker. The whole
+point of the build is to create it. In that case:
+- Do NOT output BLOCKED, and do NOT create a separate guardrails issue.
+- In guardrails-report.md, mark this a BOOTSTRAP build: list what's missing and
+  state that the executor must ESTABLISH this tooling as the task — there are no
+  existing test/lint/typecheck commands to rely on yet.
+- Write guardrails_status: READY and OUTPUT: READY so the build proceeds to the
+  architect.
+This applies even when there is no `lastlight:bootstrap` label and the title has
+no `guardrails:` prefix — judge it from the issue's intent.
+
+Otherwise (the issue is normal feature/bug work, not about adding tooling):
 
 IF ANY BLOCKING GUARDRAIL IS MISSING (no test framework at all, or tests completely broken):
-- Use the MCP tool create_issue to create a guardrails issue in the repo with:
+- Use the MCP tool github_create_issue to create a guardrails issue in the repo with:
   - title prefixed exactly with "guardrails:" (e.g. "guardrails: no test framework configured")
   - labels including {{bootstrapLabel}} so subsequent build attempts on this issue
     can detect that the task IS to set up guardrails (the orchestrator will then
     skip the BLOCKED gate and let the executor install the missing tooling).
-- Use add_issue_comment on issue #{{issueNumber}} to link the guardrails issue
+- Use github_add_issue_comment on issue #{{issueNumber}} to link the guardrails issue
 - OUTPUT must include: BLOCKED
 
 IF ALL CRITICAL GUARDRAILS ARE PRESENT (tests work, even if linting/types are missing):