|
| 1 | +# New-session starter prompt — TDPilot DPSK4 v2.2.0→v3.0 implementation |
| 2 | + |
| 3 | +This file is the copy-pasteable first message for a fresh agent session |
| 4 | +that is picking up work on the v2.2.0→v3.0 roadmap. |
| 5 | + |
| 6 | +**To use:** copy everything between the `==== BEGIN PROMPT ====` and |
| 7 | +`==== END PROMPT ====` markers below into a new Claude Code (or other |
| 8 | +agent) session as the user's first message. |
| 9 | + |
| 10 | +The prompt is self-contained: it tells the agent where it is, what to |
| 11 | +read first, what to build, and what footguns to avoid before any code |
| 12 | +gets written. |
| 13 | + |
| 14 | +The latest version of this file lives at |
| 15 | +`docs/NEW_SESSION_PROMPT.md` on the `main` branch. If you're reading a |
| 16 | +copy that disagrees with the repo, the repo wins. |
| 17 | + |
| 18 | +--- |
| 19 | + |
| 20 | +## ==== BEGIN PROMPT ==== |
| 21 | + |
| 22 | +You're picking up work on **TDPilot DPSK4** — a TouchDesigner AI |
| 23 | +assistant. The GitHub repo is `dreamrec/TDPilot_deepseekv4`. `cd` |
| 24 | +into your local clone of it before running any commands below — this |
| 25 | +prompt uses `<REPO_ROOT>` as a placeholder for whatever path you |
| 26 | +cloned to. |
| 27 | + |
| 28 | +### Current state |
| 29 | + |
| 30 | +- Latest shipped release: **v2.1.5** (May 2026 — Codex P2 follow-up |
| 31 | + on v2.1.4's `isWorkingAgentState` idle-suffix predicate bug). |
| 32 | +- Most recent merged PR: **#32** (AGENTS.md added at repo root). |
| 33 | +- Branch you should start from: `origin/main`. |
| 34 | + |
| 35 | +### Today's task |
| 36 | + |
| 37 | +Start work on **Phase 0** of the v2.2.0→v3.0 roadmap. Phase 0 is |
| 38 | +foundation plumbing — no user-visible UX yet — that subsequent phases |
| 39 | +need to ship safely. |
| 40 | + |
| 41 | +The full multi-month plan lives in |
| 42 | +[`docs/ROADMAP.md`](./ROADMAP.md). Phase 0 is at |
| 43 | +`docs/ROADMAP.md` lines 56–86 (search for `## Phase 0`). |
| 44 | + |
| 45 | +### Before you write any code |
| 46 | + |
| 47 | +Read these three files, in order. They override anything you remember |
| 48 | +from training: |
| 49 | + |
| 50 | +1. **[`AGENTS.md`](../AGENTS.md)** at the repo root — the fresh-agent |
| 51 | + kit: critical naming pins, the two .tox files, the canonical |
| 52 | + Textport rebuild recipe, the 7-version-manifest lockstep, the |
| 53 | + 12-step release ritual, DeepSeek operating rules, and TD-specific |
| 54 | + gotchas. Don't skim — every section solves a real bug we've |
| 55 | + already hit. |
| 56 | +2. **[`docs/ROADMAP.md`](./ROADMAP.md)** — the plan itself. Read |
| 57 | + "How to use this doc", "North-star vision", "Competitive context", |
| 58 | + then drill into Phase 0. |
| 59 | +3. **`CHANGELOG.md`** (top entry) — what just shipped in v2.1.5, so |
| 60 | + you understand the "before" state your Phase 0 changes will sit on |
| 61 | + top of. |
| 62 | + |
| 63 | +### The 3 deliverables of Phase 0 |
| 64 | + |
| 65 | +(Direct from `docs/ROADMAP.md` "Phase 0 — Foundation".) |
| 66 | + |
| 67 | +1. **`td_component/tdpilot_api_features.py`** — central feature-flag |
| 68 | + registry. Reads COMP params first, then env vars, then |
| 69 | + `config.json`, then declarative `FLAGS` dict defaults. Tests can |
| 70 | + monkey-patch. Skeleton structure: |
| 71 | + |
| 72 | + ```python |
| 73 | + FLAGS = { |
| 74 | + "AUTO_ROLLBACK": {"default": True, "since": "2.2.0"}, |
| 75 | + "CYCLE_DETECT": {"default": True, "since": "2.2.0"}, |
| 76 | + "PLAN_PREVIEW": {"default": False, "since": "2.5.0"}, |
| 77 | + # ... |
| 78 | + } |
| 79 | + def is_enabled(flag_name: str) -> bool: ... |
| 80 | + def get(flag_name: str): ... |
| 81 | + ``` |
| 82 | + |
| 83 | + Add this file to `_API_TOX_SOURCE_FILES` in |
| 84 | + `td_component/build_tdpilot_api_tox.py` so the freshness gate |
| 85 | + picks it up. |
| 86 | + |
| 87 | +2. **`scripts/bench_chat_pipe.py`** — runs N canonical chat turns |
| 88 | + against the mock-DeepSeek fixture machinery already in |
| 89 | + `tests/_mock_deepseek.py` (see memory: PR-20 Mock-DeepSeek |
| 90 | + architecture). Reports per-tool latency, total turn time, token |
| 91 | + usage. We need this baseline before measuring Phase-1 perf |
| 92 | + regressions. |
| 93 | + |
| 94 | +3. **`AGENTS.md` "Phase-PR test conventions" subsection** — codify: |
| 95 | + *every phase PR follows: source diff → unit tests → integration |
| 96 | + tests → request user tox rebuild → live verification.* This is the |
| 97 | + procedural piece that prevents tox-rebuild friction from |
| 98 | + torpedoing iteration speed. |
| 99 | + |
| 100 | +Also add `tests/test_v220_features_module.py` (~6 tests) pinning the |
| 101 | +flag-precedence rules: COMP param > env var > config.json > default. |
| 102 | + |
| 103 | +### Hard constraints — do not violate |
| 104 | + |
| 105 | +These are encoded in CI gates and pin tests; violating them = red CI. |
| 106 | + |
| 107 | +- **Package name is `tdpilot-dpsk4`**, NOT `tdpilot`. Repo is |
| 108 | + `dreamrec/TDPilot_deepseekv4`, NOT `dreamrec/TDPilot`. Tests in |
| 109 | + `tests/test_release_critical_names.py` pin this. |
| 110 | +- **Don't touch `_TOX_SOURCE_FILES` or `_API_TOX_SOURCE_FILES` lists |
| 111 | + with comment-only edits.** Even a `# noqa` comment bumps the source |
| 112 | + hash and fails `check_tox_freshness.py` / `check_tox_api_freshness.py` |
| 113 | + until the .tox is rebuilt in a live TD session. See memory: |
| 114 | + `feedback_noqa_on_tox_source_breaks_ci.md`. |
| 115 | +- **DeepSeek thinking blocks must be echoed back to the API |
| 116 | + verbatim.** Only strip `reasoning_content` sub-keys. Stripping |
| 117 | + `type: thinking` content blocks causes HTTP 400 on the next turn. |
| 118 | + See memory: `feedback_deepseek_thinking_blocks_must_echo.md`. |
| 119 | +- **TD Textport runs only single-line statements.** Multi-line `with` |
| 120 | + / `def` / `class` after a continuation prompt eats the next statement |
| 121 | + as SyntaxError. Always use the one-line `exec(compile(...))` form |
| 122 | + in the canonical rebuild recipe (AGENTS.md → ".tox rebuild"). |
| 123 | +- **No `time.sleep()` on TD's main thread.** It blocks cooks and |
| 124 | + invalidates diagnostics. |
| 125 | +- **Use `comp.storage`, not module globals**, for state that has to |
| 126 | + survive textDAT reloads (WS clients, registries, etc.). |
| 127 | +- **7 version manifests in lockstep.** Don't bump for this PR (Phase 0 |
| 128 | + is docs+tests+plumbing only — no version bump until end of Phase 1 |
| 129 | + when v2.2.0 ships). When you DO bump, all 7 files plus the |
| 130 | + `API_VERSION` constant move together. CI gate |
| 131 | + `scripts/check_versions.py` enforces. |
| 132 | +- **Use `gh` CLI for git ops.** Not the GitHub web UI. |
| 133 | +- **Squash-merge PRs.** Don't merge-commit. AGENTS.md has the full |
| 134 | + 12-step release ritual; key non-obvious step: `gh release create` |
| 135 | + is mandatory after `git push origin vX.Y.Z` — pushing the tag |
| 136 | + alone does NOT fire `release-assets.yml`. |
| 137 | +- **After every `git push`, check CI**: `gh run list --branch |
| 138 | + <branch>` or `gh pr checks`. Don't claim "done" until CI is green. |
| 139 | + |
| 140 | +### First action you should take |
| 141 | + |
| 142 | +Before writing any code: |
| 143 | + |
| 144 | +```bash |
| 145 | +cd <REPO_ROOT> # your local clone of dreamrec/TDPilot_deepseekv4 |
| 146 | +git fetch origin && git checkout -b claude/v2.2.0-phase-0-foundation origin/main |
| 147 | +git log --oneline -5 # confirm 93c9a30 AGENTS.md is the tip |
| 148 | +uv sync --extra dev --frozen |
| 149 | +uv run pytest tests/ -q # baseline: 1688/1688 should pass |
| 150 | +uv run ruff check src tests scripts td_component |
| 151 | +uv run python scripts/check_versions.py |
| 152 | +uv run python scripts/check_tox_freshness.py |
| 153 | +uv run python scripts/check_tox_api_freshness.py |
| 154 | +``` |
| 155 | + |
| 156 | +If any of those fail on a clean `main`, STOP and investigate before |
| 157 | +adding Phase 0 work on top. |
| 158 | + |
| 159 | +Once the baseline is green, work through Phase 0's three deliverables |
| 160 | +in the order listed above. After source changes land, ask me (the |
| 161 | +user) to rebuild the API .tox using the canonical recipe in |
| 162 | +`AGENTS.md` (search for "tdpilot-api-tox-rebuild") — do not attempt to |
| 163 | +rebuild it yourself; the rebuild has to happen inside a running |
| 164 | +TouchDesigner session, and there are 4 specific footguns documented |
| 165 | +in that recipe. |
| 166 | + |
| 167 | +### Release flow when Phase 0 is ready |
| 168 | + |
| 169 | +Phase 0 does NOT bump version. It ships as a docs+plumbing PR like |
| 170 | +PR #31 (the post-v2.1.5 hygiene fix) or PR #32 (AGENTS.md). The flow: |
| 171 | + |
| 172 | +``` |
| 173 | +1. Commit on branch claude/v2.2.0-phase-0-foundation |
| 174 | +2. Push git push -u origin HEAD |
| 175 | +3. Open PR gh pr create --title "..." --body "..." |
| 176 | +4. Watch CI gh pr checks |
| 177 | +5. Squash-merge gh pr merge --squash |
| 178 | +6. Pull main + cleanup git checkout main && git pull && git branch -D claude/... |
| 179 | +``` |
| 180 | + |
| 181 | +When Phase 1 ships at v2.2.0, the full 12-step release ritual kicks |
| 182 | +in (see AGENTS.md). That's a separate PR. |
| 183 | + |
| 184 | +### When in doubt |
| 185 | + |
| 186 | +- Conflicting instructions? `docs/ROADMAP.md` is source-of-truth for |
| 187 | + the plan; `AGENTS.md` is source-of-truth for the workflow; this |
| 188 | + file is just the bootstrap. Defer to those. |
| 189 | +- Surprising CI failure? Check `feedback_*.md` memory files first — |
| 190 | + most production footguns are already documented there. |
| 191 | +- Unsure whether a change is "Phase 0 scope" or "Phase 1 scope"? Ask |
| 192 | + before coding. Phase boundaries matter for release-cadence |
| 193 | + discipline. |
| 194 | + |
| 195 | +Acknowledge that you've read AGENTS.md, ROADMAP.md, and the latest |
| 196 | +CHANGELOG entry. Then propose your Phase 0 implementation order before |
| 197 | +writing any code. |
| 198 | + |
| 199 | +## ==== END PROMPT ==== |
| 200 | + |
| 201 | +--- |
| 202 | + |
| 203 | +## Maintenance notes (not part of the prompt) |
| 204 | + |
| 205 | +- This file is pinned by `tests/test_release_critical_names.py`. If |
| 206 | + you rename or move it, the pin test fails until the test is updated |
| 207 | + too. Same for `docs/ROADMAP.md`. |
| 208 | +- Both docs are explicitly listed in `.gitignore` exceptions (search |
| 209 | + for `!/docs/ROADMAP.md` and `!/docs/NEW_SESSION_PROMPT.md`). The |
| 210 | + default policy under `docs/` is `/docs/*.md` deny-list — these two |
| 211 | + files plus `docs/MANUAL.md` and `docs/CHUNK_SCHEMA.md` are the only |
| 212 | + tracked free-form docs. |
| 213 | +- When v2.2.0 ships, update this prompt's "Current state" section to |
| 214 | + reflect v2.2.0 as latest and shift "Today's task" to Phase 1 or |
| 215 | + Phase 2 depending on what's next. Same drift discipline as |
| 216 | + AGENTS.md. |
| 217 | +- The prompt deliberately inlines the 7-or-so worst footguns rather |
| 218 | + than punting everything to AGENTS.md. If a future agent skips |
| 219 | + AGENTS.md (they will), the inlined constraints still protect the |
| 220 | + repo from the most expensive mistakes. |
0 commit comments