tekton/TASKS.md

AI Agent Workflow Guide for Tekton Dash

This document tells AI agents how to work on Tekton Dash tasks end-to-end.

---

1. Task Source: Notion MCP

All tasks live on the "TektonDash - Armageddon PR Tasks" Notion board.

https://www.notion.so/danchiego-game/36433be43b29800c8422ed5bdd65671b?v=36433be43b2980de8635000c0a910a0d

Finding Tasks

CRITICAL: Always start by finding tasks from Notion. Priority order: P0 > P1 > P2 > P3. Status order: In Progress > To Do.

Example search for "Gauntlet" tasks:

Use: mcp_notion_API_post_search
  query: "[Gauntlet]" or task name
  filter: {"property": "object", "value": "page"}

Reading a Task

CRITICAL: The Description field contains the actual implementation requirements. TASKS.md defines workflow procedure only — each task's unique problem and solution are in Notion's Description field.

Always read full task details:

Use: mcp_notion_API_retrieve_a_page
  page_id: "<task_page_id_from_search>"

Each task page has these properties:

Property	Type	Purpose
Name	title	Task title, e.g. [Gauntlet] #1 Game Mode Registration
Status	select	To Do → In Progress → Done
Priority	select	P0 (critical) / P1 / P2 / P3
Effort	select	S - Small / M - Medium / L - Large / XL - Epic
Sprint	select	Alpha / Beta / Release
ProjectType	select	CORE / CLIENT / SERVER / INFRA
Description	rich_text	Full task description — read this to understand what to do
Acceptance	checkbox	Check when task is verified complete
DueDate	date	Optional deadline
UnitTest	date	Optional test completion date

Task Lifecycle

To Do → In Progress → Done

CRITICAL WORKFLOW:

1. Read task from Notion: Use mcp_notion_API_retrieve_a_page(page_id="...") to get full task details
2. Read Description field carefully: This contains the actual implementation requirements — file names, function signatures, integration points, RPC patterns, etc.
3. Implement exactly what Description specifies: Don't invent your own approach — follow the Description's technical requirements
4. Write unit tests: Follow pattern in tests/ directory (see GUT_SETUP_SKILLS.md)
5. Update changelog: Add entry to CHANGELOG_DRAFT.md (consumer-facing language, not technical jargon)
6. Version management: Check git diff for existing version changes (see Version Bumping section below)
7. Mark complete in Notion: Set Status → Done, check Acceptance ✅

Use: mcp_notion_API_patch_page
  page_id: "<task_page_id>"
  properties: {"Status": {"select": {"name": "Done"}}, "Acceptance": {"checkbox": true}}

---

2. Code Structure

Path	Purpose
scripts/game_mode.gd	GameMode enum + helpers (add new modes here)
scripts/managers/	All game mode managers (lobby, stop_n_go, portal, gauntlet)
scenes/main.gd	Central orchestrator — init, setup, game start routing
tests/	GUT unit tests — one file per task/feature

Adding a New Game Mode

1. Add enum to scripts/game_mode.gd → update from_string(), mode_to_string(), get_all_modes(), is_restricted()
2. Add mode name to LobbyManager.available_game_modes in lobby_manager.gd
3. Add arena name to _update_available_areas() in lobby_manager.gd
4. Add manager var + init branch in main.gd _init_managers()
5. Add setup branch in _setup_host_game() and _setup_client_game()
6. Add start branch in _start_game()
7. Add background in _apply_arena_background()

---

3. Unit Testing

Pattern

All tests extend GutTest and live in tests/. Naming: test_<feature>.gd

extends GutTest

func before_all():
    gut.p("=== Feature Tests [Task ID] ===")

func test_something():
    assert_eq(actual, expected, "Description")

func after_all():
    gut.p("=== Feature Tests Complete ===")

Running Tests

run_tests.cmd                              # all tests
run_tests.cmd test_gauntlet_registration   # specific test

Reports saved to test_reports/ with timestamps.

---

4. Version Bumping

Before bumping, check git for existing uncommitted version changes:

git diff --cached -- project.godot CHANGELOG_DRAFT.md
git diff -- project.godot CHANGELOG_DRAFT.md

If version changes already exist (staged or unstaged):

→ APPEND your changelog bullet to the existing version block in CHANGELOG_DRAFT.md → DO NOT bump project.godot or export_presets.cfg — you're joining an in-progress batch

If NO version changes exist (clean state):

→ BUMP version (increment patch: 2.3.5 → 2.3.6) → UPDATE all locations below

Version appears in 4 locations — all must match:

File	Field
CHANGELOG_DRAFT.md	## [X.Y.Z] — YYYY-MM-DD header
project.godot	config/version="X.Y.Z"
export_presets.cfg	application/file_version and application/product_version (per preset)
export_presets.cfg	export_path filenames containing version
export_presets.cfg	version/name (Android preset)

Changelog Style

Entries are consumer-facing (readable by players). No internal jargon.

## [2.3.6] — 2026-05-22
- Added new game mode: Candy Cannon Survival

Bad: "Added GAUNTLET = 3 to GameMode.Mode enum" Good: "Added new game mode: Candy Cannon Survival"

---

5. Key Conventions

• Caveman Mode: Be terse. No filler. Execute first, talk second.
• Read task from Notion FIRST: Always use mcp_notion_API_retrieve_a_page to get the Description field before implementing
• Description field is the spec: TASKS.md is workflow procedure only. Each task's unique requirements (file names, function signatures, RPC patterns, integration points) are in Notion's Description field
• Read before edit: Always check whole files before modifying .gd, .tscn, .tres, .res files
• Notion status flow: To Do → In Progress → Done (never skip steps)
• Test everything: Every completed task gets a test_<feature>.gd in tests/
• GUT framework: Tests use the Godot Unit Test (GUT) addon at addons/gut/
• Version discipline: Check git diff -- project.godot CHANGELOG_DRAFT.md before bumping version (see Version Bumping section)