specrails-core 4.8.2 → 4.9.1

package/templates/codex-skills/implement/SKILL.md

@@ -12,6 +12,14 @@ verdicts, and close the ticket. The role instructions live in
 their own skills — your message to each spawn invokes the right
 role via `$skill_name`.
 
+**Repository location.** Your working directory may NOT be the source repo.
+`openspec/**`, `.git`, and the source live under `${SPECRAILS_REPO_DIR:-.}`
+(unset ⇒ `.` ⇒ classic in-repo run). Run every `openspec`/`git` CLI command
+from the repo — `(cd "${SPECRAILS_REPO_DIR:-.}" && …)` — and read change
+artefacts under `${SPECRAILS_REPO_DIR:-.}/openspec/...`. The ticket store
+`.specrails/local-tickets.json` is run-state and stays relative to the working
+directory.
+
 **This is explicit permission to use `spawn_agent`.** The user
 wants the multi-agent split. Do not collapse the work into a
 single turn.
@@ -94,9 +102,10 @@ the combo and you'll burn a turn on the retry.
 
 ### 0. Bootstrap + agent discovery
 
-1. Confirm `pwd` matches `git rev-parse --show-toplevel`. If not,
-   `cd` to the root.
-2. Load the ticket (skip for free-form invocations):
+1. Confirm the repo root with `git -C "${SPECRAILS_REPO_DIR:-.}" rev-parse --show-toplevel`
+   (the source repo is `${SPECRAILS_REPO_DIR:-.}`; unset ⇒ `.`).
+2. Load the ticket (skip for free-form invocations) — the ticket store is
+   run-state, relative to the working directory:
    `jq '.tickets["<ID>"]' .specrails/local-tickets.json`
 3. **List the installed rail skills**:
    `ls .codex/skills/rails/`
@@ -318,15 +327,15 @@ performs the lifecycle close:
 
 The reviewer rail's archive-only mode must run these checks:
 
-1. Re-confirm every task box in `openspec/changes/<slug>/tasks.md`
+1. Re-confirm every task box in `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<slug>/tasks.md`
    is ticked (`- [x]`) and the change validates:
-   `openspec validate "<slug>" --strict`.
-2. Archive it: `openspec archive "<slug>" -y` — this updates the
-   main specs and moves the change to `openspec/changes/archive/`.
+   `(cd "${SPECRAILS_REPO_DIR:-.}" && openspec validate "<slug>" --strict)`.
+2. Archive it: `(cd "${SPECRAILS_REPO_DIR:-.}" && openspec archive "<slug>" -y)` — this updates the
+   main specs and moves the change to `${SPECRAILS_REPO_DIR:-.}/openspec/changes/archive/`.
 3. **Verify the archive landed — do NOT assume success.** Confirm
-   `openspec/changes/archive/` now contains the slug
-   (`ls -d openspec/changes/archive/*<slug>* 2>/dev/null`) AND that
-   `openspec/changes/<slug>/` is gone. If the archive directory is
+   `${SPECRAILS_REPO_DIR:-.}/openspec/changes/archive/` now contains the slug
+   (`ls -d "${SPECRAILS_REPO_DIR:-.}"/openspec/changes/archive/*<slug>* 2>/dev/null`) AND that
+   `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<slug>/` is gone. If the archive directory is
    absent, archiving FAILED.
 4. If `openspec validate`, `openspec archive`, or the step-3
    verification fails: do NOT mark the ticket `done`. Treat the run

package/templates/codex-skills/rails/sr-architect/SKILL.md

@@ -10,10 +10,17 @@ orchestrator already loaded the ticket and surveyed the repo before
 spawning you. Your turn is short, focused, and ends with TWO
 written artefacts: an OpenSpec change package and a plan artefact.
 
+**Repository location.** `openspec/**`, `.git`, and the source live under
+`${SPECRAILS_REPO_DIR:-.}` (unset ⇒ `.` ⇒ classic in-repo run). Run every
+`openspec` CLI command from the repo — `(cd "${SPECRAILS_REPO_DIR:-.}" && openspec …)`
+— and read/write change artefacts under `${SPECRAILS_REPO_DIR:-.}/openspec/...`.
+Your plan artefact under `.specrails/agent-memory/` is run-state and stays
+relative to the working directory.
+
 ## Your scope
 
 You **plan**. You do not write production code. You do not edit
-source files outside `openspec/` and `.specrails/agent-memory/`.
+source files outside `${SPECRAILS_REPO_DIR:-.}/openspec/` and `.specrails/agent-memory/`.
 
 ## What you produce
 
@@ -25,15 +32,15 @@ scaffolding so the change is registered with a workflow schema and
 stays trackable by `openspec status`. Run:
 
 ```
-openspec new change "<slug>" --schema spec-driven
+(cd "${SPECRAILS_REPO_DIR:-.}" && openspec new change "<slug>" --schema spec-driven)
 ```
 
 where `<slug>` is a kebab-case derivation of the ticket title
 (e.g. ticket "Build a Playable Tetris Game" → `add-tetris-game`).
-This creates `openspec/changes/<slug>/.openspec.yaml`.
+This creates `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<slug>/.openspec.yaml`.
 
 - If the command fails because OpenSpec isn't initialised in this
-  repo, run `openspec init . --tools codex --force` once, then
+  repo, run `(cd "${SPECRAILS_REPO_DIR:-.}" && openspec init . --tools codex --force)` once, then
   re-run `openspec new change …`.
 - If the change directory already exists from a prior run,
   **reuse** it (idempotent) — skip the `new change` call.
@@ -44,10 +51,10 @@ tasks). Check the order and what's still outstanding at any time
 with:
 
 ```
-openspec status --change "<slug>" --json
+(cd "${SPECRAILS_REPO_DIR:-.}" && openspec status --change "<slug>" --json)
 ```
 
-Write these four artefacts into `openspec/changes/<slug>/`:
+Write these four artefacts into `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<slug>/`:
 
 **`proposal.md`** — the change's executive summary:
 
@@ -256,9 +263,11 @@ on the touched files as a fallback.>
 When BOTH the OpenSpec change package and the plan artefact are
 written:
 
-1. **Validate the change with the OpenSpec CLI** (mandatory):
+1. **Validate the change with the OpenSpec CLI** (mandatory). The
+   OpenSpec project root is `${SPECRAILS_REPO_DIR:-.}` (the repo),
+   NOT the workspace cwd — so run it scoped to the repo:
    ```
-   openspec validate "<slug>"
+   (cd "${SPECRAILS_REPO_DIR:-.}" && openspec validate "<slug>")
    ```
    If validation reports structural errors, fix the offending
    artefact and re-run until it passes. Do not hand off a change

package/templates/codex-skills/rails/sr-backend-developer/SKILL.md

@@ -15,8 +15,11 @@ for changes that are neither, `$sr-developer`.
 ## Your scope
 
 Same TDD contract as `$sr-developer` — read the architect's
-plan, walk `openspec/changes/<slug>/tasks.md` in order, write
+plan, walk `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<slug>/tasks.md` in order, write
 the failing test first, then production code, re-run, tick.
+(openspec + the source files named in `tasks.md` live under
+`${SPECRAILS_REPO_DIR:-.}` — unset ⇒ `.` ⇒ classic in-repo run; edit each
+source file as `${SPECRAILS_REPO_DIR:-.}/<path>`.)
 
 What's different: you bias the test surface toward integration
 and contract correctness, not isolated unit happy paths.

package/templates/codex-skills/rails/sr-developer/SKILL.md

@@ -5,6 +5,15 @@ license: MIT
 compatibility: "Codex-native. Designed to run as a full-history sub-agent fork of the implement orchestrator."
 ---
 
+**Repository location.** Your working directory may NOT be the source
+repo. `openspec/**` and the source files named in `tasks.md` (repo-relative
+paths like `src/foo.ts`) live under `${SPECRAILS_REPO_DIR:-.}` — unset ⇒ `.`
+⇒ byte-identical to a classic in-repo run. Read openspec from
+`${SPECRAILS_REPO_DIR:-.}/openspec/...` and edit every source file as
+`${SPECRAILS_REPO_DIR:-.}/<path>`. Run-state you write (`.specrails/agent-memory/`)
+stays relative to the working directory; `.specrails/local-tickets.json` is
+likewise relative (and owned by the orchestrator — you never write it).
+
 You are the **developer** in the specrails implement pipeline. The
 architect produced an OpenSpec change package (proposal + design +
 tasks + spec deltas) and a plan artefact. Your job is to **apply**
@@ -27,14 +36,14 @@ note it in your reply — do not block on the architect.
 1. **Read the inputs**, in this order:
    - `<plan-path>` (the architect's plan artefact under
      `.specrails/agent-memory/explanations/`).
-   - `openspec/changes/<slug>/proposal.md` — the why + what.
-   - `openspec/changes/<slug>/design.md` — the deep design.
+   - `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<slug>/proposal.md` — the why + what.
+   - `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<slug>/design.md` — the deep design.
      Read **every section**, especially "Architecture", "Data
      shapes", "State & lifecycle", "Public API / surface",
      "Trade-offs" (so you know what NOT to revisit), and "Open
      questions".
-   - `openspec/changes/<slug>/tasks.md` — your execution checklist.
-   - `openspec/changes/<slug>/specs/<cap>/spec.md` — the
+   - `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<slug>/tasks.md` — your execution checklist.
+   - `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<slug>/specs/<cap>/spec.md` — the
      behavioural contracts the tests must encode.
 
    **About design.md's "Open questions" section** — if the

package/templates/codex-skills/rails/sr-doc-sync/SKILL.md

@@ -29,8 +29,9 @@ Two ways:
   specrails-managed:start -->` … `<!--
   specrails-managed:end -->` block. Outside that block
   is user-authored; don't touch it.
-- `docs/` (any markdown files).
-- `openspec/specs/<capability>/spec.md` (capabilities
+- `${SPECRAILS_REPO_DIR:-.}/docs/` (any markdown files; repo-resident — unset
+  `SPECRAILS_REPO_DIR` ⇒ `.` ⇒ classic in-repo run).
+- `${SPECRAILS_REPO_DIR:-.}/openspec/specs/<capability>/spec.md` (capabilities
   documentation — drift here is the most serious; this
   is the contract).
 - Inline JSDoc / TSDoc / Python docstrings on exported

package/templates/codex-skills/rails/sr-frontend-developer/SKILL.md

@@ -15,9 +15,12 @@ instead.
 ## Your scope
 
 Same TDD contract as `$sr-developer` — read the architect's
-plan, walk `openspec/changes/<slug>/tasks.md` in order, write
+plan, walk `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<slug>/tasks.md` in order, write
 the failing test first, then the production code, then re-run.
 Tick boxes only after observing the expected runner state.
+(openspec + the source files named in `tasks.md` live under
+`${SPECRAILS_REPO_DIR:-.}` — unset ⇒ `.` ⇒ classic in-repo run; edit each
+source file as `${SPECRAILS_REPO_DIR:-.}/<path>`.)
 
 What's different: you bias the test surface toward UI.
 

package/templates/codex-skills/rails/sr-product-manager/SKILL.md

@@ -25,14 +25,16 @@ Two ways:
 
 ### 1. Read the existing artefacts
 
-- `README.md` (project intent and surface).
-- `openspec/specs/` (existing specs — what the product
+  (Repo-resident reads live under `${SPECRAILS_REPO_DIR:-.}` — unset ⇒ `.` ⇒
+  classic in-repo run.)
+- `${SPECRAILS_REPO_DIR:-.}/README.md` (project intent and surface).
+- `${SPECRAILS_REPO_DIR:-.}/openspec/specs/` (existing specs — what the product
   contract is today).
-- `.specrails/local-tickets.json` (existing backlog —
-  don't propose duplicates).
-- A representative slice of the source code (5-10 files,
-  drawn from the relevant theme).
-- The desktop app's own `openspec/specs/` if relevant
+- `.specrails/local-tickets.json` (existing backlog — run-state, relative to
+  the working directory — don't propose duplicates).
+- A representative slice of the source code (5-10 files under
+  `${SPECRAILS_REPO_DIR:-.}`, drawn from the relevant theme).
+- The desktop app's own `${SPECRAILS_REPO_DIR:-.}/openspec/specs/` if relevant
   (cross-component changes).
 
 ### 2. Identify gaps

package/templates/codex-skills/rails/sr-reviewer/SKILL.md

@@ -11,6 +11,12 @@ implemented it. Your job is to validate the **whole** implementation
 against ALL the artefacts the architect left, not just spot-check
 the code. You emit a structured verdict and never touch the code.
 
+**Repository location.** `openspec/**`, `.git`, and the source live under
+`${SPECRAILS_REPO_DIR:-.}` (unset ⇒ `.` ⇒ classic in-repo run). Read change
+artefacts from `${SPECRAILS_REPO_DIR:-.}/openspec/...`, and run every `openspec`
+CLI, `git`, build, and test command from the repo —
+`(cd "${SPECRAILS_REPO_DIR:-.}" && …)`.
+
 ## Your scope
 
 You **validate**. You read every artefact, you re-run every check,
@@ -23,12 +29,12 @@ the completed OpenSpec change with the `openspec` CLI.
 
 ### 1. Validate the OpenSpec change package
 
-Load `openspec/changes/<slug>/` (the orchestrator gave you the
+Load `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<slug>/` (the orchestrator gave you the
 slug). **Run the OpenSpec validator first** — it is the canonical
 structural check and is mandatory:
 
 ```
-openspec validate "<slug>" --strict --json
+(cd "${SPECRAILS_REPO_DIR:-.}" && openspec validate "<slug>" --strict --json)
 ```
 
 A non-empty error list is a blocker finding: record each under
@@ -200,13 +206,13 @@ orchestrator has aggregated all reviewer verdicts. Therefore:
 When archiving is authorized and the verdict is clean, run these exact
 checks in order:
 
-1. Re-run `openspec validate "<slug>" --strict`.
-2. Read `openspec/changes/<slug>/tasks.md` and search for unchecked
+1. Re-run `(cd "${SPECRAILS_REPO_DIR:-.}" && openspec validate "<slug>" --strict)`.
+2. Read `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<slug>/tasks.md` and search for unchecked
    tasks (`- [ ]`). If any remain, do not archive; change the verdict to
    `fix needed: OpenSpec tasks remain unchecked`.
-3. Run `openspec archive "<slug>" -y`.
-4. Verify the archive landed: confirm `openspec/changes/<slug>/` is gone
-   and `openspec/changes/archive/` contains a directory whose name
+3. Run `(cd "${SPECRAILS_REPO_DIR:-.}" && openspec archive "<slug>" -y)`.
+4. Verify the archive landed: confirm `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<slug>/` is gone
+   and `${SPECRAILS_REPO_DIR:-.}/openspec/changes/archive/` contains a directory whose name
    includes `<slug>`.
 
 If validation, archive, or verification fails, do not report `clean`.

package/templates/codex-skills/retry/SKILL.md

@@ -13,9 +13,14 @@ You are NOT a separate pipeline. You inspect what `$implement`
 left behind, summarise the current state, and re-invoke
 `$implement` with a hint about what's already in place. The
 implement skill is idempotent — architect reuses an existing
-`openspec/changes/<slug>/`, developer detects ticked tasks and
+`${SPECRAILS_REPO_DIR:-.}/openspec/changes/<slug>/`, developer detects ticked tasks and
 already-correct files, reviewer re-validates from scratch.
 
+**Repository location.** `openspec/**` and `.git` live under
+`${SPECRAILS_REPO_DIR:-.}` (unset ⇒ `.` ⇒ classic in-repo run); inspect change
+artefacts there. The ticket store and `.specrails/agent-memory/` are run-state,
+relative to the working directory.
+
 ## How the user invokes you
 
 - `$retry #N` — retry the implement run for ticket `N`.
@@ -25,8 +30,8 @@ already-correct files, reviewer re-validates from scratch.
 
 ### 0. Locate the prior run's artefacts
 
-1. Confirm `pwd` matches the git root.
-2. Load the ticket:
+1. Confirm the repo root with `git -C "${SPECRAILS_REPO_DIR:-.}" rev-parse --show-toplevel`.
+2. Load the ticket (run-state, relative to the working directory):
    `jq '.tickets["<ID>"]' .specrails/local-tickets.json`. If
    the ticket doesn't exist, stop and report.
 3. Inspect what's already on disk for this ticket:
@@ -34,11 +39,11 @@ already-correct files, reviewer re-validates from scratch.
      `.specrails/agent-memory/explanations/` named
      `*-architect-ticket-<ID>.md`. List the latest.
    - **OpenSpec change package**: any
-     `openspec/changes/<slug>/` whose proposal.md mentions
+     `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<slug>/` whose proposal.md mentions
      the ticket title or whose tasks.md has tasks scoped to
      the ticket. Find the slug.
    - **tasks.md progress**: count `[x]` vs `[ ]` boxes in
-     `openspec/changes/<slug>/tasks.md`.
+     `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<slug>/tasks.md`.
    - **Reviewer verdict**: latest matching
      `*-reviewer-ticket-<ID>.confidence-score.json`. Read
      the issues list and overall score.

package/templates/commands/specrails/implement.md

@@ -14,6 +14,20 @@ Full OpenSpec lifecycle with specialized agents: architect designs, developer im
 
 ---
 
+## Repository location (read first)
+
+Your working directory may NOT be the user's source repository. **Repo-resident** things — the source code, `openspec/**`, `.git`, and the GitHub remote — live under **`${SPECRAILS_REPO_DIR:-.}`**. The spawner sets `SPECRAILS_REPO_DIR` to the repo path; **when it is unset it defaults to `.` (the current directory), making every command below byte-identical to a classic in-repo run.**
+
+Rules used throughout this pipeline:
+- **openspec reads/writes** → `${SPECRAILS_REPO_DIR:-.}/openspec/...`
+- **git commands** → `git -C "${SPECRAILS_REPO_DIR:-.}" ...`
+- **`gh` commands** (issue/PR — they need the repo's remote) → run them from the repo: `(cd "${SPECRAILS_REPO_DIR:-.}" && gh ...)`
+- **worktree merge-back** → the merge *target* side (the main working tree) is `${SPECRAILS_REPO_DIR:-.}/<file>`
+
+**Run-state stays with the working directory** (NOT the repo): `.claude/pipeline-state/`, `.claude/agent-memory/`, `.claude/backlog-cache.json`, and the dry-run cache `.claude/.dry-run/` are all written relative to the current directory. **Profile/agent files** (`.claude/agents/sr-*.md`) are likewise resolved relative to the current directory — do NOT prefix them with `${SPECRAILS_REPO_DIR:-.}`.
+
+---
+
 ## Phase -1: Environment Setup (cloud pre-flight)
 
 **This phase runs BEFORE anything else.** Detect if we're in a cloud/remote environment and ensure all required tools are available.
@@ -353,7 +367,7 @@ If the write fails: print `[backlog-cache] Warning: could not write cache. Confl
 For each resolved issue number, run:
 
 ```bash
-gh issue view {number} --json number,title,state,assignees,labels,body,updatedAt
+(cd "${SPECRAILS_REPO_DIR:-.}" && gh issue view {number} --json number,title,state,assignees,labels,body,updatedAt)
 ```
 
 Build a snapshot object for each issue:
@@ -502,7 +516,7 @@ Otherwise, re-fetch each issue in scope and diff against the Phase 0 snapshot:
 **If `BACKLOG_PROVIDER=github`:** For each issue number in `ISSUE_REFS`:
 
 ```bash
-gh issue view {number} --json number,title,state,assignees,labels,body,updatedAt
+(cd "${SPECRAILS_REPO_DIR:-.}" && gh issue view {number} --json number,title,state,assignees,labels,body,updatedAt)
 ```
 
 If the `gh` command returns non-zero (issue deleted or inaccessible): treat as a CRITICAL conflict — field `"state"`, was `<cached state>`, now `"deleted"`.
@@ -558,7 +572,7 @@ For `body_sha` rows in the table, display only the first 8 characters of each SH
 
 For each chosen idea, launch an **sr-architect** agent (`subagent_type: sr-architect`, `run_in_background: true`).
 
-Each architect creates OpenSpec artifacts in `openspec/changes/<name>/`.
+Each architect creates OpenSpec artifacts in `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<name>/`.
 
 Each agent's prompt should include:
 - Description of the feature
@@ -574,7 +588,7 @@ After all architect agents complete, before launching any developer agent:
 
 #### Step 1: Extract file references
 
-For each `openspec/changes/<name>/tasks.md`, extract all paths listed under `**Files:**` entries (both `Create:` and `Modify:` lines). Normalize paths: strip leading `./`.
+For each `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<name>/tasks.md`, extract all paths listed under `**Files:**` entries (both `Create:` and `Modify:` lines). Normalize paths: strip leading `./`.
 
 #### Step 2: Build the shared-file registry
 
@@ -653,7 +667,7 @@ Before launching any developer agent, run a trivial Bash command to confirm Bash
 
 #### Choosing the right developer agent
 
-For each feature, read `openspec/changes/<name>/tasks.md` and classify every task by its layer tags and file references.
+For each feature, read `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<name>/tasks.md` and classify every task by its layer tags and file references.
 
 **Step 1 — Classify tasks into layers:**
 
@@ -857,6 +871,8 @@ If a doc-sync agent fails or times out:
 
 #### Merge Algorithm
 
+The merge **target** (the main repo working tree where merged files land) is `<target>` = **`${SPECRAILS_REPO_DIR:-.}`**. Every `<target>/<file>` below therefore resolves to `${SPECRAILS_REPO_DIR:-.}/<file>` so merged code lands in the real repo, not the working directory. (`<worktree-path>` is an absolute git-worktree path supplied by the runtime; `git -C <worktree-path>` already targets it directly.)
+
 Process features in `MERGE_ORDER` sequence. For each feature:
 
 **Step 1: Identify changed files**
@@ -871,7 +887,7 @@ Split into `exclusive_files` (only this feature modifies them) and `shared_files
 
 Copy directly from worktree to target:
 ```bash
-cp <worktree-path>/<file> <target>/<file>
+cp <worktree-path>/<file> "${SPECRAILS_REPO_DIR:-.}"/<file>
 ```
 Log: `Copied (exclusive): <file>`
 
@@ -880,7 +896,7 @@ Log: `Copied (exclusive): <file>`
 For each shared file, choose strategy by file type:
 
 **Strategy A — Markdown section-aware merge** (`.md` files):
-1. Read base: current content of `<target>/<file>`.
+1. Read base: current content of `${SPECRAILS_REPO_DIR:-.}/<file>` (the merge target).
 2. Read incoming: `<worktree-path>/<file>`.
 3. Parse both into sections using `##` heading boundaries (heading line + all content until next `##` or EOF).
 4. Build section maps: `{heading_text: content}` for base and incoming.
@@ -897,7 +913,7 @@ For each shared file, choose strategy by file type:
      >>>>>>> base
      ```
      Log: `CONFLICT: <file> — section "<heading>" requires manual resolution.`
-6. Write merged result to `<target>/<file>`.
+6. Write merged result to `${SPECRAILS_REPO_DIR:-.}/<file>` (the merge target).
 
 **Strategy B — Unified diff sequential apply** (all other file types):
 1. Generate incoming diff against original `main`:
@@ -906,7 +922,7 @@ For each shared file, choose strategy by file type:
    ```
 2. Apply to current target:
    ```bash
-   patch --forward --fuzz=3 <target>/<file> < <diff>
+   patch --forward --fuzz=3 "${SPECRAILS_REPO_DIR:-.}"/<file> < <diff>
    ```
 3. If `patch` succeeds: log `Merged (diff-apply): <file>`.
 4. If `patch` fails: insert conflict markers around rejected hunks. Log: `CONFLICT: <file> — N hunks rejected.`
@@ -949,7 +965,7 @@ If `MERGE_REPORT.requires_resolution` is non-empty:
 
 Build `CONTEXT_BUNDLES` from the features in `MERGE_ORDER`:
 ```
-{ "<feature-a>": "openspec/changes/<feature-a>/context-bundle.md", "<feature-b>": "openspec/changes/<feature-b>/context-bundle.md" }
+{ "<feature-a>": "${SPECRAILS_REPO_DIR:-.}/openspec/changes/<feature-a>/context-bundle.md", "<feature-b>": "${SPECRAILS_REPO_DIR:-.}/openspec/changes/<feature-b>/context-bundle.md" }
 ```
 
 Load merge resolver config from `.claude/merge-resolver-config.json` if it exists. Extract `confidence_threshold` (default: 70) and `mode` (default: `auto`).
@@ -959,7 +975,7 @@ Construct the `sr-merge-resolver` agent prompt with:
 - `CONTEXT_BUNDLES`: the map above
 - `CONFIDENCE_THRESHOLD`: from config or default (70)
 - `RESOLUTION_MODE`: from config or default (`auto`)
-- `REPORT_PATH`: `openspec/changes/<first-feature-in-MERGE_ORDER>/merge-resolution-report.md`
+- `REPORT_PATH`: `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<first-feature-in-MERGE_ORDER>/merge-resolution-report.md`
 
 Launch the **sr-merge-resolver** agent (`subagent_type: sr-merge-resolver`, foreground, `run_in_background: false`). Wait for it to complete.
 
@@ -1107,7 +1123,7 @@ After the generalist reviewer agent completes, evaluate the confidence score bef
 
 #### Step 1 — Read score file
 
-Path: `openspec/changes/<name>/confidence-score.json`
+Path: `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<name>/confidence-score.json`
 
 - If the file does not exist:
   - Set `CONFIDENCE_STATUS=MISSING`
@@ -1213,7 +1229,7 @@ Re-fetch each issue in `ISSUE_REFS` and diff against `.claude/backlog-cache.json
 
 **If `BACKLOG_PROVIDER=github`:**
 ```bash
-gh issue view {number} --json number,title,state,assignees,labels,body,updatedAt
+(cd "${SPECRAILS_REPO_DIR:-.}" && gh issue view {number} --json number,title,state,assignees,labels,body,updatedAt)
 ```
 
 If the cache file is missing or malformed JSON at this point: log `[conflict-check] Warning: cache file missing or unreadable. Skipping diff for this run.` and proceed to Phase 4c (treat as clean).
@@ -1270,13 +1286,15 @@ This phase respects the `GIT_AUTO` and `BACKLOG_WRITE` settings from configurati
 
 #### If `GIT_AUTO=true` (automatic shipping)
 
-1. Create branch from `main`: `git checkout -b feat/<descriptive-name>`
-2. One commit per feature with descriptive messages
-3. If the reviewer modified files, create an additional commit: `fix: resolve CI issues (reviewer)`
-4. Push with `-u` flag: `git push -u origin <branch-name>`
-5. Create PR (if GitHub CLI is available):
+All git operations run against the repo via `git -C "${SPECRAILS_REPO_DIR:-.}"`, and `gh` runs from inside the repo so it can detect the remote.
+
+1. Create branch from `main`: `git -C "${SPECRAILS_REPO_DIR:-.}" checkout -b feat/<descriptive-name>`
+2. One commit per feature with descriptive messages (`git -C "${SPECRAILS_REPO_DIR:-.}" add … && git -C "${SPECRAILS_REPO_DIR:-.}" commit -m …`)
+3. If the reviewer modified files, create an additional commit: `git -C "${SPECRAILS_REPO_DIR:-.}" commit -m "fix: resolve CI issues (reviewer)"`
+4. Push with `-u` flag: `git -C "${SPECRAILS_REPO_DIR:-.}" push -u origin <branch-name>`
+5. Create PR (if GitHub CLI is available), running it from the repo:
    ```bash
-   {{PR_CREATE_CMD}}
+   (cd "${SPECRAILS_REPO_DIR:-.}" && {{PR_CREATE_CMD}})
    ```
    If `gh` is not authenticated, print a compare URL for manual PR creation.
 
@@ -1293,9 +1311,9 @@ All implementation is complete and CI checks pass.
 - [list all modified/created files per feature]
 
 ### Suggested Next Steps
-1. Review the changes: `git diff`
-2. Create a branch: `git checkout -b feat/<name>`
-3. Stage and commit: `git add <files> && git commit -m "feat: ..."`
+1. Review the changes: `git -C "${SPECRAILS_REPO_DIR:-.}" diff`
+2. Create a branch: `git -C "${SPECRAILS_REPO_DIR:-.}" checkout -b feat/<name>`
+3. Stage and commit: `git -C "${SPECRAILS_REPO_DIR:-.}" add <files> && git -C "${SPECRAILS_REPO_DIR:-.}" commit -m "feat: ..."`
 4. Push and create PR manually
 ```
 
@@ -1307,7 +1325,7 @@ All implementation is complete and CI checks pass.
   {{BACKLOG_COMMENT_CMD}}
   ```
   - **Local:** Update the ticket status to `"done"` using `{{BACKLOG_UPDATE_CMD}}` and add a comment: `"Implemented in PR #XX. All acceptance criteria met."` via `{{BACKLOG_COMMENT_CMD}}`. Local tickets are closed directly — there is no auto-close-on-merge mechanism.
-  - **GitHub:** `gh issue comment {number} --body "Implemented in PR #XX. All acceptance criteria met."` — do NOT close the issue explicitly. Use `Closes #N` in the PR body so GitHub auto-closes on merge.
+  - **GitHub:** `(cd "${SPECRAILS_REPO_DIR:-.}" && gh issue comment {number} --body "Implemented in PR #XX. All acceptance criteria met.")` — do NOT close the issue explicitly. Use `Closes #N` in the PR body so GitHub auto-closes on merge.
   - **JIRA:** `jira issue comment {key} --message "Implemented in PR #XX. All acceptance criteria met."`
   - For GitHub/JIRA: ensure the PR body includes `Closes #N` for each fully resolved issue (auto-closes on merge)
 - For partially resolved issues/tickets: add a comment noting progress:

package/templates/commands/specrails/retry.md

@@ -19,6 +19,8 @@ Resume a failed `/specrails:implement` run for **{{PROJECT_NAME}}**. Reads pipel
 
 **MANDATORY: Follow this pipeline exactly. Do NOT skip phases or re-run phases that already succeeded. Read all context from the pipeline state file — do not rely on memory. Do not re-implement anything yourself; delegate to the same agents used by `/specrails:implement`.**
 
+**Repository location.** Your working directory may NOT be the user's source repository. Repo-resident things — `openspec/**`, source, `.git`, the GitHub remote — live under **`${SPECRAILS_REPO_DIR:-.}`** (set by the spawner; unset ⇒ `.` ⇒ byte-identical to a classic in-repo run). The pipeline-state file itself is **run-state**, read from `.claude/pipeline-state/` relative to the working directory — do NOT prefix it. The `openspec_artifacts` value stored in that file is a repo-relative path (`openspec/changes/<name>/`); prefix it with `${SPECRAILS_REPO_DIR:-.}/` when you read those files on disk. All git/PR operations are delegated to `/specrails:implement` Phase 4c, which already runs them against the repo.
+
 **Input:** $ARGUMENTS — accepted forms:
 
 1. `<feature-name>` — kebab-case feature name matching a `.claude/pipeline-state/<feature-name>.json` file
@@ -214,7 +216,7 @@ Wait for all architects to complete.
 Before launching, verify architect artifacts exist:
 
 ```bash
-ls <OPENSPEC_ARTIFACTS>tasks.md <OPENSPEC_ARTIFACTS>context-bundle.md
+ls "${SPECRAILS_REPO_DIR:-.}/<OPENSPEC_ARTIFACTS>tasks.md" "${SPECRAILS_REPO_DIR:-.}/<OPENSPEC_ARTIFACTS>context-bundle.md"
 ```
 
 If missing and `RESUME_PHASE=developer`: print:

package/templates/gemini-commands/implement.toml

@@ -58,14 +58,18 @@ The change is archived BY THE REVIEWER as part of a passing review — never by
 
 ## Pipeline
 
-0. **Bootstrap.** Confirm `pwd` is the git repo root and load the ticket from
-   `.specrails/local-tickets.json` (or use the free-form description). Then go
-   STRAIGHT to phase 1 — do not analyse, design, scaffold, or write anything
-   yourself; the architect does that.
+0. **Bootstrap.** The source repo (with `openspec/**` and `.git`) lives at
+   `${SPECRAILS_REPO_DIR:-.}` — when `SPECRAILS_REPO_DIR` is unset it defaults to
+   `.`, i.e. your current directory is the repo (classic behaviour). Confirm the
+   repo root with `git -C "${SPECRAILS_REPO_DIR:-.}" rev-parse --show-toplevel`,
+   then load the ticket from `.specrails/local-tickets.json` (run-state — relative
+   to the working directory, NOT the repo). Then go STRAIGHT to phase 1 — do not
+   analyse, design, scaffold, or write anything yourself; the architect does that.
 
 1. **DESIGN — `invoke_agent` `sr-architect`.** Pass it the ticket/description.
    It creates an OpenSpec change (proposal + spec deltas + tasks) under
-   `openspec/changes/<id>/` and validates it (`openspec validate <id> --strict`).
+   `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<id>/` and validates it
+   (`openspec validate <id> --strict`).
    Apply the outcome rules above.
 
 2. **APPLY — `invoke_agent` `sr-developer`.** Only after the architect reports
@@ -89,7 +93,7 @@ The change is archived BY THE REVIEWER as part of a passing review — never by
    or ambiguous review: the reviewer's PASS is the ONLY gate to archive.
 
 4. **ARCHIVE (verify only).** Confirm the change moved under
-   `openspec/changes/archive/`. If the reviewer PASSED but the change was somehow
+   `${SPECRAILS_REPO_DIR:-.}/openspec/changes/archive/`. If the reviewer PASSED but the change was somehow
    not archived, re-`invoke_agent` `sr-reviewer` to complete it. Never archive by
    hand to substitute for the reviewer.