joryirving/windowstead #63: Add CONTRIBUTING.md and docs/ structure

[itsmiso-ai]

Fixes #63. Added the requested documentation structure:

• CONTRIBUTING.md — setup, dev workflow, testing, and PR process
• docs/DESIGN.md — architecture, data model, save format, key systems
• docs/SPEC.md — gameplay mechanics, resource/economy system, worker AI decisions

All docs are written from the actual codebase: (~800 lines), , and the scene graph.

[smurf-bot]

✅ Automated recommendation: APPROVE

Analysis engine: MiniMax-M2.7@https://api.minimax.io/v1

Review Summary

PR #68: Add CONTRIBUTING.md and docs/ structure — Approved.

This PR adds three documentation files addressing issue #63: a contributing guide, design document, and specification. All additions are new files (285 total lines) with no modifications to existing code.

---

Change-by-Change Findings

1. CONTRIBUTING.md (67 lines)

• Prerequisites correctly list Godot 4.2.2 and the shipped binary at .tools/Godot_v4.2.2-stable_linux.x86_64
• Project structure accurately describes the one-scene, two-scripts architecture
• Dev workflow section outlines branch naming conventions (fix/issue-NN-short, feat/short-description) consistent with this repo's history
• Testing section correctly references the headless smoke test at res://tests/test_runner.gd
• Code style notes (GDScript idioms, String() casts, commenting dense logic) align with the ~800-line main.gd mentioned

2. docs/DESIGN.md (107 lines)

• Scene graph tree accurately reflects the actual hierarchy (Control root → Backdrop → Margin → Root HBox → Left/CrewList)
• Scripts table correctly identifies main.gd (~800 lines) and game_state.gd (autoload singleton)
• State dictionary schema matches the save format keys: tick, harvested, resources, priority_order, workers, tiles, builds, next_build_id, events, save_version
• Tile kinds table (ground, tree, rock, berries, stockpile, foundation, hut/workshop/garden) is accurate
• Structure progression (hut → workshop → garden with unlock requirements) is correctly documented
• Save format notes (version tracking, layout bounds checking) match game_state.gd behavior

3. docs/SPEC.md (111 lines)

• Worker names "Jun" and "Mara" match the codebase
• Resource nodes (trees 6, rocks 5, berries 4) are correctly specified
• Ambient events (every 66 ticks) with correct event types (trail mix, break, supply drop)
• Building costs tables are accurate: hut (6 wood, 2 stone), workshop (4 wood, 6 stone), garden (3 wood, 1 stone)
• Structure bonuses match documented values: hut +1 food, workshop +0.16 build speed, garden +3 food
• Worker AI documentation (priority order, Manhattan distance selection, gather/haul/build tasks) is accurate
• Tick system values (base 0.9s, speed multipliers ×1.6/×1.0/×0.65, focus ×2.5) are correct
• UI anchor modes (right 30×5, left 7×16, bottom 30×5) are accurately documented

---

Standards Compliance

✅ AGENTS.md compliance: This PR is a documentation-only addition. The AGENTS.md guidelines focus on UX constraints (bottom-dock-first, tile geometry, avoiding sidebar UI regressions) and implementation patterns. Documentation files do not trigger these concerns.

✅ Accuracy: File paths (scenes/main.tscn, scripts/main.gd, scripts/game_state.gd, tests/test_runner.gd) match the actual repository structure. The ~800-line reference for main.gd is corroborated by the codebase scan.

✅ Internal consistency: All three docs cross-reference consistently (e.g., DESIGN.md documents the data model that SPEC.md describes interacting with).

---

Unknowns / Needs Verification

⚠️ Linked issues: Could not fetch the actual issue #63 text (URL fetch failed), but the PR body explicitly states this PR addresses issue #63, and the git log confirms the commit is linked to PR #68.

ℹ️ Repository history verification: The git grep scan confirmed the referenced file paths (scenes/main.tscn, scripts/main.gd, scripts/game_state.gd, tests/test_runner.gd) exist in the codebase. The export presets file (export_presets.cfg) was referenced but not scanned; standard Godot project conventions suggest it exists.