From 628c07e70e9ab22b8f24455a9aa8495f9a544179 Mon Sep 17 00:00:00 2001 From: Ryan Kegel Date: Tue, 13 Oct 2026 21:44:40 -0400 Subject: [PATCH] refactor: Update developer instructions and spec pipeline descriptions for clarity and improved validation processes --- .codex/agents/developer.toml | 8 ++++---- .codex/skills/spec-pipeline/SKILL.md | 13 ++++++++----- 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/.codex/agents/developer.toml b/.codex/agents/developer.toml index 5b23c23..10ac43b 100644 --- a/.codex/agents/developer.toml +++ b/.codex/agents/developer.toml @@ -12,11 +12,11 @@ You are a Godot 4 / GDScript 2.0 implementation developer. Adhere to coding stan - **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". -- **Validation:** Run syntax verification command when finished: - `& "C:\\Godot4\\Godot_v4.7.1-stable_win64_console.exe" --headless --check-only --script "res://path/to/script.gd" --path "C:\\Godot4\\stickman"` +- **Validation:** Resolve the Godot 4.7.1 binary for the current platform using `AGENTS.md`. Run syntax/import checks, relevant existing suites, and focused automated tests of the feature's observable outcomes. For runtime interactions, exercise a minimal scene or fixture through the real production path, advance frames or physics ticks, and assert the result. Fix failures and rerun the affected checks. Inspect rendered output when available; state clearly when visual behavior could not be checked. ## Output Format - **Summary:** 1-2 lines on changes made. -- **Code Edits:** Show only modified snippet/function blocks with surrounding context lines. -""" \ No newline at end of file +- **Code Edits:** Show only modified snippet/function blocks with surrounding context lines when code excerpts are useful. +- **Verification:** Report commands, results, the behavior observed or measured, and any remaining user checks. Do not equate syntax success or debug output with a working feature. +""" diff --git a/.codex/skills/spec-pipeline/SKILL.md b/.codex/skills/spec-pipeline/SKILL.md index 64bbde3..d0f526e 100644 --- a/.codex/skills/spec-pipeline/SKILL.md +++ b/.codex/skills/spec-pipeline/SKILL.md @@ -1,6 +1,6 @@ --- name: spec-pipeline -description: "Lean implementation loop: UI/UX (Ideas -> Spec) -> Architect (Clarify -> Spec) -> Developer -> User Verification." +description: "Stickman Studio feature workflow: UI/UX and architecture specs, implementation, agent-run behavior verification, then user verification." --- ## Execution Logic @@ -27,15 +27,18 @@ description: "Lean implementation loop: UI/UX (Ideas -> Spec) -> Architect (Clar 4. **Phase 1b: User Feedback & Spec Generation** - User approves, modifies, or selects choices from `@architect`'s proposal. - `@architect` writes the finalized specification to `docs/specs/[feature-name].md` and logs decisions in `docs/architecture/tech_debt_and_optimizations.md`. + - The spec states observable acceptance outcomes and the user path that produces each one. For interactions involving physics, timing, saving/loading, or multiple systems, name a small repeatable runtime scenario and what to measure; do not prescribe a test implementation unless it is needed to protect a specific behavior. - **STOP:** Wait for final user sign-off on the spec before invoking developer. -5. **Phase 2: Implementation & Engine Validation** +5. **Phase 2: Implementation & Agent Verification** - `@developer` updates code and scenes using targeted diffs based on `docs/specs/[feature-name].md`. - - `@developer` runs headless syntax verification. - - If static check fails, `@developer` fixes the code immediately. + - `@developer` runs Godot syntax/import checks and focused existing regression suites, then fixes failures. + - `@developer` adds focused automated coverage where it can meaningfully verify the feature's observable acceptance outcomes. For cross-system or runtime behavior, construct a small repeatable scene or fixture (in memory or as a saved scene), use the real production spawning/input/action paths where practical, advance frames or physics ticks, and assert the resulting state. A check that nodes, signals, layers, or helper calls exist is insufficient when the requirement concerns what actually happens during play. + - When the outcome is visual or interactive, run the affected scene and inspect rendered output or a capture where the environment permits. Record what was observed; a headless launch or successful screenshot command alone does not prove visual correctness. If rendering or GUI access is unavailable, report that limit explicitly and leave a focused visual check for the user. + - `@developer` reruns the relevant checks after fixes and reports commands, pass/fail results, the measured behavior, and any unverified acceptance outcome. Do not claim a feature is verified from syntax checks or debug prints alone. 6. **Phase 3: User Hand-off (Stop)** - - Present the changes to the user to test inside the Godot Editor. + - Present the implementation and agent verification evidence. Give the user only the remaining visual, usability, or environment-dependent checks to perform in the Godot Editor; clearly identify any acceptance outcome the agent could not verify. 7. **Phase 4: Documentation (Triggered manually by user)** - Only call `@writer` after the user confirms: "Feature verified and working."