# 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`

```gdscript
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

```cmd
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:**

```cmd
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.

```markdown
## [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)