tekton/SKILLS.md

# SKILLS.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=36633be43b29803891cd000c6f6e5c5f

### Finding Tasks

Should always start with this to find tasks, find the highest priority task that is not done, second is In Progress, then To Do. 

example, query for "Gauntlet"
```
Use: mcp_notion-mcp-server_API-post-search
  query: "[Gauntlet]" or task name
  filter: {"property": "object", "value": "page"}
```

### Reading a Task

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

1. **Pick up task**: Set `Status` → `In Progress`
2. **Do the work**: Read `Description`, implement the changes
3. **Write unit tests**: Follow pattern in `tests/` directory
4. **Mark complete**: Set `Status` → `Done`, check `Acceptance` ✅
5. **Update changelog**: Add entry to `CHANGELOG_DRAFT.md` (consumer language)
6. **Bump version**: Update `project.godot` + `export_presets.cfg`

```
Use: mcp_notion-mcp-server_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 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/`.