From 44afaa313393edb75ce554e3e9f8d86b73ba918d Mon Sep 17 00:00:00 2001 From: Ryan Kegel Date: Sat, 24 Oct 2026 01:17:26 -0400 Subject: [PATCH] feat: establish feature worktree guidelines across agents and skills --- .codex/agents/architect.toml | 4 ++++ .codex/agents/designer.toml | 1 + .codex/agents/developer.toml | 1 + .codex/skills/feature-ideation/SKILL.md | 4 +++- .codex/skills/spec-pipeline/SKILL.md | 8 ++++++++ .gitignore | 1 + AGENTS.md | 11 +++++++++++ 7 files changed, 29 insertions(+), 1 deletion(-) diff --git a/.codex/agents/architect.toml b/.codex/agents/architect.toml index 24206ff..16d4dce 100644 --- a/.codex/agents/architect.toml +++ b/.codex/agents/architect.toml @@ -13,6 +13,10 @@ You are the Lead Systems Architect specializing in Godot 4 and idiomatic GDScrip 3. **Design:** Define API payload shapes, static GDScript type hints, node hierarchies, and signal flows. 4. **Log:** Append trade-offs to `docs/architecture/tech_debt_and_optimizations.md`. +## 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. + ### Shared Stage inspector UI For an in-stage selected-object inspector, first read `docs/specs/stage_panel_ui_system.md` and inspect `scripts/shared/stage_ui/` plus the `stage_panels` theme tokens. Use the existing diff --git a/.codex/agents/designer.toml b/.codex/agents/designer.toml index eafcb48..bf8dff3 100644 --- a/.codex/agents/designer.toml +++ b/.codex/agents/designer.toml @@ -40,6 +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. - 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. diff --git a/.codex/agents/developer.toml b/.codex/agents/developer.toml index 10ac43b..a0f3827 100644 --- a/.codex/agents/developer.toml +++ b/.codex/agents/developer.toml @@ -9,6 +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. - **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". diff --git a/.codex/skills/feature-ideation/SKILL.md b/.codex/skills/feature-ideation/SKILL.md index e3ecee8..016f103 100644 --- a/.codex/skills/feature-ideation/SKILL.md +++ b/.codex/skills/feature-ideation/SKILL.md @@ -37,6 +37,8 @@ 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, have Designer create the accepted product/design brief at `docs/plans/phase__.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/`. +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. + +Have Designer create the accepted product/design brief at `docs/plans/phase__.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/`. Do not overwrite an existing phase brief without the user's direction. Confirm the resulting file exists, update the matching backlog entry to `Planned` with a link to the brief, then tell the user where the plan is using a clickable local file link. Stop there; this skill creates the design handoff, not the technical spec or implementation. diff --git a/.codex/skills/spec-pipeline/SKILL.md b/.codex/skills/spec-pipeline/SKILL.md index 6127a87..f719bb1 100644 --- a/.codex/skills/spec-pipeline/SKILL.md +++ b/.codex/skills/spec-pipeline/SKILL.md @@ -5,6 +5,14 @@ description: "Stickman Studio feature workflow: UI/UX and architecture specs, im ## Execution Logic +### 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. + +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/` on `feature/` 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. + +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. + 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. - Before proposing, mocking, reviewing, or suggesting UI/UX changes, `@uiux` reads `docs/guides/editor_visual_style_guide.md` and checks the relevant implemented controls/specs. Treat the guide as the current visual baseline; distinguish implemented behavior from recommendations and explain intentional departures. This also applies to direct `@uiux` requests outside the pipeline. diff --git a/.gitignore b/.gitignore index 77f4676..5fbff10 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ # Godot 4+ specific ignores .godot/ +.worktrees/ .images/ /android/ addons/ diff --git a/AGENTS.md b/AGENTS.md index 81092bb..7faf321 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,6 +6,17 @@ - Headless tests + command-line scene playback exist (see "Command-line testing & debug playback" below); the GUI editor runs via `run/main_scene`. - **Main scene:** `res://scenes/main.tscn` (set as `run/main_scene` in `project.godot`; hosts the Stickman Editor) +## 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. +- 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`. +- If the current checkout is already the matching feature worktree, continue there. Otherwise, create a new worktree at `.worktrees/` with branch `feature/`, based on the integration branch (usually `main`). Include the phase number in the slug when known, such as `phase-20-stage-search`. +- 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`. +- 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. +- 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. +- 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. + ## Repository layout - `scripts/` and `scenes/` stay as separate roots with matching feature groups. Editor controllers live in `scripts/editors/{stickman,prop,stage}`; stage, stickman runtime, props, terrain, and speech systems live in `scripts/{stage,characters/stickman,props,terrain,speech}`.