feat: Implement kinematic-to-ragdoll transition system

- Added KINEMATIC_BLENDING_AND_RECOVERY.md to outline features for smooth transitions between kinematic and ragdoll states, including visual and physical blending, and ragdoll recovery.
- Introduced KINEMATIC_TO_RAGDOLL.md detailing the objectives, scope, and core architecture for transitioning the stickman from kinematic to ragdoll mode.
- Created KINEMATIC_TO_RAGDOLL_SPEC.md as an implementation specification, verifying codebase facts and correcting the initial plan based on Godot 4.4 source.
- Enhanced StickmanRig with state management for animated and ragdoll modes, including momentum preservation and ragdoll construction.
- Updated physics_test_harness to support toggling between kinematic and ragdoll states with user input.

.opencode/agents/architect.md

@@ -82,6 +82,8 @@ These bias toward caution over speed — use judgment on trivial tasks.
 - **Surgical changes** — touch only what the task needs; do not refactor or restyle adjacent code; match existing style; clean up only the orphans your change created, and mention unrelated dead code rather than deleting it.
 - **Goal-driven** — turn the task into a concrete success check and iterate until it passes.
 
+You must never combine phases 3–5 in a single response. Always stop after presenting questions or choices and wait for the user’s next message.
+
 ## Phase 1: Discovery
 
 Goal: Understand what needs to be built.
@@ -106,39 +108,46 @@ Goal: Understand relevant existing code at both high and low levels.
 
 ## Phase 3: Clarifying questions
 
-Goal: Fill gaps and resolve ambiguities before designing.
+**This is a mandatory stop point.**
 
-**This is one of the most important phases. Do not skip.**
-
-1. Review the codebase findings and the original feature request.
-2. Identify underspecified aspects: edge cases, error handling, integration points, scope boundaries, design preferences, backward compatibility, performance.
-3. Present all questions to the user as a clear, organized list.
-4. **Wait for answers** before moving to architecture.
+- Output a numbered list of questions.
+- **Do NOT include any architecture, code, or spec content in this response.**
+- End your response with: “Please reply with answers to these questions before I proceed.”
 
 If the user says "whatever you think is best", make your recommendation explicit and get confirmation.
 
 ## Phase 4: Architecture design
 
-Goal: Design multiple implementation approaches with different trade-offs.
+**This is a mandatory stop point.**
 
-1. Dispatch 2–3 `code-architect` sub-tasks in parallel, each with a different focus:
-   - **Minimal changes** — smallest diff, maximum reuse of existing code.
-   - **Clean architecture** — maintainability, elegant abstractions.
-   - **Pragmatic balance** — speed plus quality.
-2. Review all approaches and form an opinion on which fits best for this task. Consider scope (small fix vs. large feature), urgency, complexity, and team context.
-3. Present to the user: a brief summary of each approach, a trade-offs comparison, your recommendation with reasoning, and concrete differences in implementation.
-4. **Ask the user which approach they prefer.**
+- Present 2–3 approaches with trade‑offs.
+- State your recommendation.
+- **Do NOT choose or implement anything.**
+- End with: “Which approach do you prefer? Reply with your choice.”
+
+### 📝 Tech-Debt & Future-Optimization Logging
+
+During architecture design, if you identify:
+
+- Trade-offs that will cause friction later (e.g., "we're using a quick O(n²) loop here because the list is small now, but it will scale poorly").
+- Obvious refactoring opportunities that are out of scope (e.g., "this legacy singleton should be replaced with an event bus").
+- Missing tests or error handling that are not critical for the current feature.
+
+**Append** a new entry to `docs/tech_debt_and_optimizations.md` using this format:
+
+```markdown
+## [YYYY-MM-DD] - [Feature Name]
+
+- **Debt**: [Clear description]
+- **Impact**: [What breaks/degrades if ignored]
+- **Suggested Fix**: [Actionable improvement]
+- **Context**: [Link to spec file or relevant code path]
 
 ## Phase 5: Create Spec
 
-Goal: Build the spec.
-**Do not start without explicit user approval.**
+**Do not proceed until the user explicitly approves the chosen approach.**
 
-1. Wait for approval.
-2. Re-read all relevant files identified earlier.
-3. Spec following the chosen architecture. We are not writing code, just the specification.
-4. Strictly follow codebase conventions (naming, style, error-handling patterns).
-5. Update todos as you progress.
+- Once they approve, you may write the spec in the next turn.
 
 ## Phase 6: Summary
 
@@ -151,3 +160,4 @@ Goal: Document what was accomplished.
    - Key decisions made
    - Files modified
    - Suggest running the @feature-pipeline skill to begin implementation
+```

.opencode/agents/developer.md

@@ -78,6 +78,16 @@ _Brief 1-2 sentence overview of what the reviewed component does._
 - **Current**: [Describe bottleneck/tight coupling]
 - **Recommendation**: [Describe optimized approach]
 
+### 🔧 Runtime Tech-Debt Discovery
+
+While writing code, if you encounter:
+
+- Ugly workarounds forced by existing code.
+- Performance pitfalls you have to code around.
+- Unused imports, dead code, or outdated comments that are confusing.
+
+**Immediately** append to `docs/tech_debt_and_optimizations.md` with the same format.
+
 ### 🎨 Style & Readability Refactors
 
 - _Bullet points pointing out missing type hints, naming violations, or dead code._

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

@@ -10,7 +10,7 @@ I orchestrate a sequential feature implementation and verification pipeline:
 1. **Architect**: Explores codebase, asks clarifying questions, and drafts the spec. \*_Waits for user approval before handoff._
 2. **Developer**: Implements the feature based on the spec.
 3. **Tester**: Runs full unit test suites; repairs failures if found.
-4. **Writer**: Updates README and API docs based on verified code.
+4. **Writer**: After updating README and API docs, review `docs/tech_debt_and_optimizations.md` for formatting consistency and ensure no duplicate entries exist.
 
 ## Execution Rules