Add development environment readiness stage

docs/configuration.md

@@ -301,7 +301,13 @@ repositories, `patchmill init` defaults them to project-local skill paths. In an
 interactive terminal, init asks whether to add generated config and skills to
 git, add Patchmill files to `.gitignore`, or add Patchmill files to
 `.git/info/exclude`. Non-interactive and `--yes` runs keep the files local by
-adding `patchmill.config.json` and `.patchmill/` to `.git/info/exclude`:
+adding `patchmill.config.json` and `.patchmill/` to `.git/info/exclude`.
+
+`developmentEnvironment` is optional. When configured, `patchmill run-once` runs
+that skill from the issue worktree after the plan is available and before the
+implementation skill starts. The skill should prepare and verify local runtime
+prerequisites, then return either `ready` or `not-ready`. When the key is
+omitted, implementation starts exactly as it did before this feature.
 
 ```json
 {
@@ -313,6 +319,18 @@ adding `patchmill.config.json` and `.patchmill/` to `.git/info/exclude`:
 }
 ```
 
+A repository can opt into development-environment setup without changing the
+required keys:
+
+```json
+{
+  "skills": {
+    "developmentEnvironment": ".patchmill/skills/bootstrapping-tilt-worktrees",
+    "implementation": ".patchmill/skills/subagent-dev-with-codex-and-thermo-reviews"
+  }
+}
+```
+
 Path-like skill references resolve relative to the config file directory. When
 choosing **Add to git**, init stages `patchmill.config.json`,
 `.patchmill/skills`, and `.gitignore`; `.gitignore` keeps `.patchmill/pi-agent`,
@@ -339,6 +357,8 @@ rather than `patchmill.config.json`:
 
 Optional skill keys let a repository add procedure at specific workflow stages:
 
+- `developmentEnvironment`: local runtime setup and development-environment
+  verification before implementation starts.
 - `toolchain`: setup and validation conventions.
 - `review`: explicit review passes.
 - `visualEvidence`: screenshots or other UI proof.

docs/issue-agent-workflows.md

@@ -181,7 +181,12 @@ flowchart TD
   R -->|approval missing| R2[Comment plan ready, add plan-review, restore ready label, finish]
   R -->|approved or not required| S[Render subagent support guidance]
   S --> T[Ensure issue worktree and branch]
-  T --> U[Run Pi implementation prompt in worktree]
+  T --> U0{Development-environment skill configured?}
+  U0 -->|yes| U1[Run Pi development-environment prompt in worktree]
+  U1 --> U2{Development environment result}
+  U2 -->|not-ready| U3[Restore retryable label and return operator remediation]
+  U2 -->|ready| U[Run Pi implementation prompt in worktree]
+  U0 -->|no| U
   U --> V{Pi result}
   V -->|blocked| BQ
   V -->|pr-created| W[Assert todo completion, upload PR visual evidence if present]
@@ -192,6 +197,7 @@ flowchart TD
   AC --> AD[Run cleanup hooks]
   AD --> AE[Return final JSON]
   U -->|unexpected failure| AF[Record failure, leave in-progress, post failure comment once]
+  U1 -->|unexpected failure| AF
 ```
 
 ### Issue selection and safety gates
@@ -279,6 +285,22 @@ finished, and exits with `plan-created` or `plan-found`. Once the configured
 plan-approved label is present, a later `run-once` reuses the plan and proceeds
 to implementation.
 
+### Optional development-environment Pi prompt
+
+If `skills.developmentEnvironment` is configured, `run-once` runs a separate Pi
+prompt from the issue worktree before implementation. The prompt uses the
+configured development-environment skill and accepts only `ready` or `not-ready`
+final JSON.
+
+`ready` records a summary, evidence, and optional non-secret environment details
+for the later implementation prompt. Patchmill serializes those fields as
+untrusted JSON handoff data so implementation agents do not treat field contents
+as instructions. `not-ready` stops the run before implementation, removes the
+in-progress claim, leaves the issue retryable, and returns operator remediation
+in the final command output. Development environment failures do not use
+issue-style `questions` because they describe local environment repair, not
+product requirements.
+
 ### Implementation Pi prompt
 
 After a plan exists and implementation is allowed, `buildImplementationPrompt()`
@@ -288,6 +310,8 @@ asks Pi to implement from the issue worktree. The prompt includes:
 - the untrusted issue-content boundary;
 - subagent support guidance for delegated implementation and review roles;
 - resume context, when continuing an existing run;
+- untrusted development-environment JSON handoff data when the optional
+  development-environment stage ran;
 - issue body and relevant comments;
 - required project context-file instructions;
 - the implementation task-contract instructions;
@@ -320,7 +344,7 @@ It always renders:
 
 For initialized repositories, `skills.implementation` is set to the project path
 `.patchmill/skills/subagent-driven-development`. The recommended skill pack also
-installs two opt-in final-readiness alternatives:
+installs two opt-in final-review alternatives:
 `.patchmill/skills/subagent-dev-with-codex-and-thermo-reviews` for repositories
 that want task-by-task worker/reviewer handoffs before final Codex and
 thermo-nuclear full-worktree Pi reviewer loops, and
@@ -374,5 +398,5 @@ Console progress includes:
 
 The final JSON summary includes the run log path and, depending on status, issue
 number, plan path, worktree path, branch, PR URL or merge commit, commits,
-validation, review summary, landing decision, visual evidence, or blocker
-questions.
+validation, review summary, landing decision, visual evidence, blocker
+questions, or development-environment remediation.