feat: update worktree guidelines for agents and skills to confirm user preferences before creating worktrees

.codex/agents/architect.toml

@@ -15,7 +15,7 @@ You are the Lead Systems Architect specializing in Godot 4 and idiomatic GDScrip
 
 ## Feature worktree
 
-For a feature spec, use the absolute feature worktree path and branch supplied by the orchestrating session. Read and write all feature documents there. Do not switch branches or write into the shared checkout. If no worktree path was supplied, stop before writing and tell the orchestrator to establish one.
+Before writing a feature document, confirm that the orchestrator has asked the user whether this task should use a Git worktree and supplied the selected project path and branch. If the user has not chosen yet, ask the orchestrator to get that preference before writing. Use the supplied path whether it is a worktree or the current checkout; do not create a worktree or switch branches yourself. Follow `AGENTS.md`.
 
 ### Shared Stage inspector UI
 For an in-stage selected-object inspector, first read `docs/specs/stage_panel_ui_system.md`

.codex/agents/artist.toml

@@ -32,6 +32,8 @@ Clothing currently has no standalone format. Author clothing as layered shapes i
 
 ## Review workflow
 
+Before creating an asset review bundle, confirm that the orchestrator has asked the user whether this task should use a Git worktree and supplied the selected project path and branch. If the preference is missing, ask the orchestrator to get it before writing. Use the selected path whether it is a worktree or the current checkout; do not create a worktree or switch branches yourself. Follow `AGENTS.md`.
+
 Create every unapproved deliverable under `content/review/artist/<request-slug>/`. Use descriptive, versioned filenames and never overwrite an existing production asset unless the user explicitly requests replacement.
 
 Each review bundle must contain:

.codex/agents/designer.toml

@@ -40,7 +40,7 @@ Wait for the user to answer before analyzing or proposing feature work.
 
 ## Editing limits
 
-- **Feature worktree:** When preparing an accepted phase brief, use the absolute feature worktree path and branch supplied by the orchestrating session, as defined in `AGENTS.md`. Write the brief and related backlog update only in that worktree. Do not switch branches or write into the shared checkout. If no feature worktree was supplied, stop before writing and tell the orchestrator it must establish one.
+- **Worktree choice:** Before preparing an accepted phase brief or updating the backlog, confirm that the orchestrator has asked the user whether this task should use a Git worktree and supplied the selected project path and branch. If the preference is missing, ask the orchestrator to get it before writing. Use the supplied path whether it is a worktree or the current checkout. Do not create a worktree, switch branches, or write into another checkout yourself. Follow `AGENTS.md`.
 - You may edit only `docs/ideas/feature_backlog.md` and accepted phase briefs under `docs/plans/` during normal use. Never edit application code, scenes, project settings, or unrelated documents.
 - Do not create a phase brief before both design acceptance and receipt of the user's phase number.
 - Keep idea discussion conversational and concise. When writing a document, summarize the resulting file and link it in your response.

.codex/agents/developer.toml

@@ -9,7 +9,7 @@ You are a Godot 4 / GDScript 2.0 implementation developer. Adhere to coding stan
 
 ## Rules
 
-- **Feature worktree:** Use the absolute feature worktree path and branch supplied by the orchestrating session, following `AGENTS.md`. Run Godot checks and make all code/scene edits in that worktree. Do not switch branches, merge, or edit the shared checkout. If the worktree path is missing, stop before editing and report it to the orchestrator.
+- **Worktree choice:** Before persistent edits, confirm that the orchestrator has asked the user whether this task should use a Git worktree and supplied the selected project path and branch. If the preference is missing, ask the orchestrator to get it before editing. Use the supplied path whether it is a worktree or the current checkout. Do not create a worktree, switch branches, merge, or edit another checkout yourself. Follow `AGENTS.md` for the selected path.
 - **Targeted Edits Only:** Do NOT output full unchanged files. Output only modified functions, concise diffs, or specific node configurations.
 - **Static Typing:** Enforce explicit type hints for all signatures and variables.
 - **Decoupling:** Follow "call down, signal up".

.codex/agents/uiux.toml

@@ -5,6 +5,10 @@ model_reasoning_effort = "high"
 sandbox_mode = "read-only"
 
 developer_instructions = """
+## Worktree choice
+
+You are read-only and must not create worktrees or write project files. For any handoff that will create project files, confirm that the orchestrator has asked the user whether to use a worktree and supplied the selected project path and branch. Do not require a worktree when the user chooses the current checkout.
+
 ## 0. Editor Visual Style Guide
 
 Before making, mocking, reviewing, or suggesting any Prop Editor or Stickman Editor UI/UX

.codex/agents/writer.toml

@@ -16,4 +16,5 @@ You are a technical writer for Godot 4 / GDScript projects. You document game ar
 
 1. **Targeted Edits Only:** Touch only the specific markdown sections affected by recent changes. Never output full unchanged files.
 2. **Scannable & Technical:** Lead directly with code blocks, tables, and structured lists. Eliminate marketing fluff or generic introductions.
+3. **Worktree Choice:** Before any persistent documentation work, confirm that the orchestrator has asked the user whether this task should use a Git worktree and supplied the selected project path and branch. If the preference is missing, ask the orchestrator to get it first. Use the selected path whether it is a worktree or the current checkout; do not create a worktree yourself.
 """

.codex/skills/asset-creation/SKILL.md

@@ -7,6 +7,10 @@ description: "Create or revise Stickman Studio props, stickmen, embedded clothin
 
 Use the `artist` subagent for project graphical-asset and animation work. This skill manages delegation, review, approval, and handoff; it does not replace the Artist's visual judgment.
 
+## Choose a worktree before creating files
+
+Before creating an asset review bundle or other project files, ask whether the user wants this task to use a Git worktree unless they have already stated a preference. For small, self-contained asset changes, offer the current checkout as the default. Wait for the answer before creating a worktree. Follow `AGENTS.md`, and pass Artist the absolute path and branch the user selected, whether that is a worktree or the current checkout. Do not require a worktree when the user declines one.
+
 ## Delegate to Artist
 
 Spawn `artist` with `agent_type: "artist"`. Reuse the same Artist for revisions while it is available. Tell it that other agents may share the workspace and that it must preserve unrelated changes.

.codex/skills/feature-ideation/SKILL.md

@@ -37,7 +37,7 @@ Treat the user's clear statement that they are ready to work on the discussed, s
 
 ## Stage 3: Write and hand off the brief
 
-Once the user is ready and the phase number is known, establish or reuse a dedicated feature worktree before writing the brief, following the `Feature branches and worktrees` rules in `AGENTS.md`. Use that same branch for the brief, later specs, implementation, and verification. Pass the absolute worktree path and branch name to Designer and ensure the brief and backlog update are written there. Do not switch or write into the shared checkout to prepare the brief.
+Once the user is ready and the phase number is known, ask whether the brief and later feature work should use a Git worktree unless the user has already stated a preference for this task. Follow the choice and the `Feature branches and worktrees` rules in `AGENTS.md`; do not create a worktree before the user answers. Use the selected checkout consistently for the brief, later specs, implementation, and verification. Pass its absolute path and current branch to Designer. Do not switch branches or write outside the selected checkout.
 
 Have Designer create the accepted product/design brief at `docs/plans/phase_<number>_<feature_slug>.md`, following `docs/plans/README.md`. The brief should cover the goal and audience, desired child outcome, behavior/flow and feedback, story or directing value where relevant, success criteria, included and excluded scope, known risks/dependencies, project references, and remaining questions for the spec-pipeline. Keep architecture/API decisions for the architect's later technical specification in `docs/specs/`.
 

.codex/skills/spec-pipeline/SKILL.md

@@ -7,11 +7,11 @@ description: "Stickman Studio feature workflow: UI/UX and architecture specs, im
 
 ### Feature branch and worktree setup
 
-For every new feature or phase that will produce project files, use one dedicated feature branch and worktree from the first persistent artifact through implementation and verification. Read-only proposals can happen before the worktree is created; create or reuse it before the first UI spec, architecture spec, design brief, asset candidate, code change, or other feature file is written.
+Before creating a worktree for a task, ask the user whether they want one and wait for the answer. For small, self-contained fixes or documentation changes, offer the current checkout as the default; for larger feature phases, explain the benefit of a dedicated worktree. Do not create a worktree before the user chooses. Keep the user's choice for the task from the first persistent artifact through implementation and verification.
 
-Follow the `Feature branches and worktrees` rules in `AGENTS.md`: inspect the current branch and worktree list, reuse a matching feature worktree when present, otherwise create `.worktrees/<feature-slug>` on `feature/<feature-slug>` from the integration branch. Include the phase number in the slug when known. Do not switch the user's shared checkout, transfer uncommitted changes without direction, or merge automatically.
+Follow the `Feature branches and worktrees` rules in `AGENTS.md`: inspect `git status --short`, the current branch, and worktree list before the first persistent change. If the user chooses the current checkout, stay on its branch. If they choose a worktree, reuse a matching one or create `.worktrees/<feature-slug>` on `feature/<feature-slug>` from the integration branch, including the phase number when known. Do not switch branches, transfer uncommitted changes without direction, or merge automatically.
 
-Pass the absolute worktree path and branch name to every delegated agent, and tell each agent to use that path for all repository reads, writes, Godot runs, and visual checks. If a delegated agent cannot target the supplied worktree, stop its file-writing work and report the issue to the orchestrator.
+Pass every delegated agent the absolute selected project path and its branch, whether that path is a worktree or the current checkout. Tell each agent to use it for all repository reads, writes, Godot runs, and visual checks. Do not stop file-writing work solely because the user chose not to use a worktree.
 
 1. **Phase 0a: UI/UX Proposal & Alternative Ideas (User-Facing Features Only)**
    - `@uiux` analyzes the user's initial idea for cognitive friction, accessibility, and kid-friendliness.

AGENTS.md

@@ -8,12 +8,12 @@
 
 ## Feature branches and worktrees
 
-- Start each new feature or phase that will create project files in a dedicated Git branch and worktree. Use the same branch from its design brief and specs through implementation and verification, so parallel features stay isolated.
+- Before creating a Git worktree for a task, ask the user whether they want this task to use one. Do not create a worktree until they answer. For small, self-contained fixes and documentation changes, offer the current checkout as the default; for larger feature phases, explain why a worktree may help and let the user choose.
-- Read-only discussion and proposals do not need a worktree. Before the first persistent feature change, inspect `git status --short`, `git branch --show-current`, and `git worktree list`.
+- Read-only discussion and proposals do not need a worktree. Before the first persistent change, inspect `git status --short`, `git branch --show-current`, and `git worktree list`.
-- If the current checkout is already the matching feature worktree, continue there. Otherwise, create a new worktree at `.worktrees/<feature-slug>` with branch `feature/<feature-slug>`, based on the integration branch (usually `main`). Include the phase number in the slug when known, such as `phase-20-stage-search`.
+- If the user chooses the current checkout, keep working on its current branch. Do not switch branches, stash, reset, clean, move, or overwrite unrelated work.
-- Example from the repository root: `git worktree add .worktrees/phase-20-stage-search -b feature/phase-20-stage-search main`. Confirm the resulting path and branch with `git worktree list` and `git branch --show-current`.
+- If the user chooses a worktree, reuse a matching one when present. Otherwise, create `.worktrees/<feature-slug>` with branch `feature/<feature-slug>`, based on the integration branch (usually `main`). Include the phase number in the slug when known, such as `phase-20-stage-search`. Example: `git worktree add .worktrees/phase-20-stage-search -b feature/phase-20-stage-search main`. Confirm the path and branch with `git worktree list` and `git branch --show-current`.
-- Reuse an existing worktree for the same feature. Do not switch branches in the user's current checkout, overwrite an existing path/branch, stash, reset, clean, or move uncommitted work. If relevant uncommitted changes need to be carried into the feature worktree, ask how to handle them before proceeding.
+- If relevant uncommitted changes need to be carried into a chosen worktree, ask how to handle them before proceeding.
-- Pass the absolute worktree path and branch name to every subagent. All project reads, writes, Godot commands, and visual checks for the feature must target that worktree. If no worktree path was supplied, do not write feature files in the shared checkout; tell the orchestrator what is missing.
+- Pass every subagent the absolute path and branch the user chose, whether that is a worktree or the current checkout. All project reads, writes, Godot commands, and visual checks must target that path. Do not require a worktree when the user chose the current checkout.
 - Do not merge feature branches automatically. Keep each feature branch available for review and merge only when the user asks or the active workflow explicitly authorizes it.
 - `.worktrees/` is a local worktree container and must remain gitignored.
 

sandbox_theme.json

@@ -159,13 +159,9 @@
       "choice_font_size": 18,
       "choice_min_width": 104,
       "choice_corner_radius": 12,
-      "choice_content_inset_x": 8,
-      "choice_content_inset_y": 6,
       "compact_choice_height": 50,
       "compact_choice_preview_height": 22,
       "compact_choice_font_size": 16,
-      "compact_choice_content_inset": 4,
-      "compact_choice_content_separation": 2,
       "compact_grid_gap": 6,
       "compact_layout_max_width": 600,
       "compact_layout_max_height": 460,

scripts/shared/stage_ui/stage_ground_finish_chooser.gd

@@ -33,10 +33,6 @@ var _grid_gap: int = 8
 var _compact_choice_height: int = 54
 var _compact_choice_preview_height: int = 22
 var _compact_choice_font_size: int = 16
-var _choice_content_inset_x: int = 8
-var _choice_content_inset_y: int = 6
-var _compact_choice_content_inset: int = 4
-var _compact_choice_content_separation: int = 2
 var _compact_grid_gap: int = 6
 var _compact_layout_max_width: int = 600
 var _compact_layout_max_height: int = 460
@@ -111,10 +107,6 @@ func _configure_theme_values() -> void:
 	_compact_choice_height = _theme_int("compact_choice_height", 50, 48, 72)
 	_compact_choice_preview_height = _theme_int("compact_choice_preview_height", 22, 16, 36)
 	_compact_choice_font_size = _theme_int("compact_choice_font_size", 16, 14, 20)
-	_choice_content_inset_x = _theme_int("choice_content_inset_x", 8, 4, 20)
-	_choice_content_inset_y = _theme_int("choice_content_inset_y", 6, 3, 16)
-	_compact_choice_content_inset = _theme_int("compact_choice_content_inset", 4, 3, 12)
-	_compact_choice_content_separation = _theme_int("compact_choice_content_separation", 2, 0, 8)
 	_compact_grid_gap = _theme_int("compact_grid_gap", 6, 4, 12)
 	_compact_layout_max_width = _theme_int("compact_layout_max_width", 600, 440, 760)
 	_compact_layout_max_height = _theme_int("compact_layout_max_height", 460, 360, 640)
@@ -166,9 +158,7 @@ func _build_choice_buttons() -> void:
 		button.focus_mode = Control.FOCUS_ALL
 		_apply_choice_style(button)
 		var contents := VBoxContainer.new()
-		contents.name = "ChoiceContent"
 		contents.set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT)
-		contents.clip_contents = true
 		contents.add_theme_constant_override("separation", 4)
 		contents.mouse_filter = Control.MOUSE_FILTER_IGNORE
 		var sample := GROUND_PREVIEW.new() as StageGroundFinishPreview
@@ -337,28 +327,13 @@ func _apply_choice_density(compact: bool) -> void:
 		var button: Button = _choice_buttons[finish_id] as Button
 		button.custom_minimum_size.y = target_height
 		_apply_choice_style(button)
-		var inset_y: float = float(_compact_choice_content_inset if compact else _choice_content_inset_y)
-		var content_separation: int = _compact_choice_content_separation if compact else 4
-		var label_height: float = 18.0 if compact else 20.0
-		var available_preview_height: float = maxf(
-			16.0,
-			target_height - inset_y * 2.0 - label_height - float(content_separation)
-		)
-		var preview_height: float = minf(target_preview_height, available_preview_height)
-		var contents: VBoxContainer = button.get_node_or_null("ChoiceContent") as VBoxContainer
-		if contents != null:
-			contents.offset_left = float(_choice_content_inset_x)
-			contents.offset_top = inset_y
-			contents.offset_right = -float(_choice_content_inset_x)
-			contents.offset_bottom = -inset_y
-			contents.add_theme_constant_override("separation", content_separation)
 		var sample: StageGroundFinishPreview = _choice_previews[finish_id] as StageGroundFinishPreview
 		if sample != null:
-			sample.custom_minimum_size.y = preview_height
+			sample.custom_minimum_size.y = target_preview_height
 		var label: Label = _choice_labels[finish_id] as Label
 		if label != null:
 			label.add_theme_font_size_override("font_size", target_font_size)
-			label.custom_minimum_size.y = label_height
+			label.custom_minimum_size.y = 18.0 if compact else 20.0
 
 
 func _focus_selected_choice() -> void:
@@ -388,9 +363,9 @@ func _choice_box(background: Color, border: Color, border_width: int) -> StyleBo
 	style.border_color = border
 	style.set_border_width_all(border_width)
 	style.set_corner_radius_all(_theme_int("choice_corner_radius", 12, 8, 24))
-	style.content_margin_left = float(_choice_content_inset_x)
+	style.content_margin_left = 8.0
-	style.content_margin_right = float(_choice_content_inset_x)
+	style.content_margin_right = 8.0
-	var vertical_padding: float = float(_compact_choice_content_inset) if _is_compact_layout else float(_choice_content_inset_y)
+	var vertical_padding: float = 2.0 if _is_compact_layout else 6.0
 	style.content_margin_top = vertical_padding
 	style.content_margin_bottom = vertical_padding
 	return style

scripts/stage/sandbox_theme.gd

@@ -134,13 +134,9 @@ func _apply_phase19_defaults() -> void:
 		"choice_font_size": 18,
 		"choice_min_width": 104,
 		"choice_corner_radius": 12,
-		"choice_content_inset_x": 8,
-		"choice_content_inset_y": 6,
 		"compact_choice_height": 50,
 		"compact_choice_preview_height": 22,
 		"compact_choice_font_size": 16,
-		"compact_choice_content_inset": 4,
-		"compact_choice_content_separation": 2,
 		"compact_grid_gap": 6,
 		"compact_layout_max_width": 600,
 		"compact_layout_max_height": 460,