Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.
description: "Tasks for the default project template"
Tasks: Default Project Template
Input: Design documents from /specs/004-default-project-template/
Prerequisites: plan.md, spec.md, research.md, data-model.md, contracts/engine-abi.md
Tests: The spec does not ask for TDD, but Constitution IV requires smoke-test coverage
for new C ABI surface, and the template is cheap to check on a real engine — so smoke
checks are included (in tests/Nota.SmokeTest, the PR gate).
Organization: Tasks are grouped by user story. US1 and US2 share one builder
(ProjectTemplate.ApplyDefault); US2 adds the return effects to it, US3 makes it the
undo/dirty baseline.
Format: [ID] [P?] [Story] Description
- [P]: Can run in parallel (different files, no dependencies)
- [Story]: Which user story this task belongs to (US1, US2, US3)
Phase 1: Setup
No setup: no new project, dependency or tool. Skipped.
Phase 2: Foundational (Blocking Prerequisites)
Purpose: The template builder skeleton and its two call sites, so every story lands in the real app.
- T001 Create
src/managed/Nota.Infrastructure/Persistence/ProjectTemplate.cs: two-line AGPL-3.0-only SPDX header plus a comment header explaining why the file exists (the default new-project content, specs/004-default-project-template);namespace Nota.Infrastructure.Persistence;public static class ProjectTemplatewithpublic static int ApplyDefault(IAudioEngine engine)documented as "Builds the default new-project content on a freshly reset engine and makes it the undo baseline. Returns the instrument track id." — body empty for now, returns -1. Match the style ofProjectService.csin the same folder - T002 In
src/managed/Nota.App/MainWindow.Files.csOnMenuNew: callProjectTemplate.ApplyDefault(Engine)right afterEngine.Reset()and the transport resets, beforeRefreshAfterLoad()(which already precedesMarkProjectClean()) - T003 In
src/managed/Nota.App/MainWindow.Recovery.csOnOpenedRecoveryCheck: beforeMarkProjectClean()(the "fresh startup project" line), callProjectTemplate.ApplyDefault(Engine)thenRefreshAfterLoad(), so the launch workspace starts from the template (FR-008). Do not touchApplyPendingRecovery/OpenProject(FR-009: those load throughProjectService.Apply, which resets first)
Checkpoint: New project and launch both run the (still empty) builder.
Phase 3: User Story 1 - New project is ready to play (Priority: P1) 🎯 MVP
Goal: A new project has one instrument track and one audio track, built exactly like tracks added by hand.
Independent Test: File → New; arrangement shows an instrument track (Nota Synth, an empty 1-bar clip) above an audio track; playing the keyboard on the instrument sounds.
- T004 [US1] In
ProjectTemplate.ApplyDefault(src/managed/Nota.Infrastructure/Persistence/ProjectTemplate.cs):int inst = engine.AddInstrumentTrack();thenengine.AddMidiClip(inst, 0.0, 4.0);(same seed clip asMainWindow.AddTrack), thenengine.AddAudioTrack();. Keep engine-assigned names and colours (FR-002, FR-006). Returninst - T005 [P] [US1] Create
tests/Nota.SmokeTest/ProjectTemplateTests.cs(SPDX header, comment header naming specs/004-default-project-template,internal static class ProjectTemplateTestswithpublic static IEnumerable<(bool ok, string label)> Run()in the style ofSnapGridTests.cs): onusing var eng = new NotaEngine()callProjectTemplate.ApplyDefault(eng); check exactly two non-return tracks in order instrument then audio (TryGetTrackInfo(0/1, …)), the instrument kind is Synth (TrackInstrumentKind == 0) with one MIDI clip at beat 0 length 4, the audio track has no clips, and the returned id is the instrument track - T006 [US1] Wire the tests into
tests/Nota.SmokeTest/Program.cs:foreach (var (ok, label) in ProjectTemplateTests.Run()) Check(ok, label);in the full run next to theSnapGridTests.Run()/HistoryTestscalls, plus a--templatestandalone switch mirroring the--gridblock
Checkpoint: US1 works in the app (new project shows two playable tracks) and in the smoke test.
Phase 4: User Story 2 - Reverb and delay sends are ready (Priority: P1)
Goal: Two returns, "Reverb" with Nota Reverb and "Delay" with Nota Delay, both fully wet; sends start silent.
Independent Test: New project → return A holds only Nota Reverb with WET ONLY on, return B only Nota Delay with WET ONLY on; raising a send adds only the effect.
- T007 [US2] In
ProjectTemplate.ApplyDefault, after the audio track:int rv = engine.AddReturnTrack(); engine.SetTrackName(rv, "Reverb"); int rd = engine.AddBuiltinDevice(rv, 2);(built-in kind 2 = Reverb) andengine.DeviceSetParam(rv, rd, 19, 1f);(Reverb param 19 = "Wet Only"); thenint dl = engine.AddReturnTrack(); engine.SetTrackName(dl, "Delay"); int dd = engine.AddBuiltinDevice(dl, 3);(kind 3 = Delay) andengine.DeviceSetParam(dl, dd, 22, 1f);(Delay param 22 = "Wet Only"). Use named constants with a short comment rather than bare numbers. Do not set sends (FR-005: they stay at their default) - T008 [US2] Extend
ProjectTemplateTests.Run()intests/Nota.SmokeTest/ProjectTemplateTests.cs: exactly two return tracks, return indices 0 and 1, named "Reverb" and "Delay"; each hasTrackDeviceCount == 1withTrackDeviceBuiltinKind2 / 3;DeviceParamName(…,19)== "Wet Only" andDeviceGetParam(…,19)is 1 on the reverb, likewise param 22 on the delay;GetTrackSend(track, 0/1)for both tracks reads the default off level (compare with a send on a track added to a fresh engine) - T009 [US2] Extend
ProjectTemplateTests.Run(): save/load round trip —ProjectService.Capture(eng, new TransportState(120, 1, false, false), warnings),ProjectService.Save(doc, tempDir, eng),ProjectService.Load(tempDir),ProjectService.Apply(loaded, eng2, tempDir)on a secondNotaEngine; check the same four tracks, names, device kinds and Wet Only values; delete the temp dir infinally(pattern:Program.csM7-6c round trip)
Checkpoint: US1 + US2 — the full template content is built and survives save/load.
Phase 5: User Story 3 - The template is the starting point, not a change (Priority: P2)
Goal: No undo steps and no "save changes?" prompt on an untouched new project.
Independent Test: File → New, press Undo → nothing happens; quit → no prompt; delete a template track, Undo → it returns.
- T010 [US3] Engine: add
void clearUndoHistory();toEngineinsrc/native/nota.engine/src/Engine.hnext tocanUndo()and implement it insrc/native/nota.engine/src/Engine.cppasundoStack_.clear(); redoStack_.clear(); undoGroupDepth_ = 0; undoGroupBase_ = 0;with a comment that the stacks hold only old authoring graphs, whichretired_keeps alive for the audio thread (message thread only). MakeEngine::reset()call it instead of repeating those lines - T011 [US3] C ABI: declare
NOTA_API void nota_engine_clear_undo_history(NotaEngine* engine);insrc/native/nota.engine/include/nota/nota_engine.hin the "Undo / redo (M6-6)" section with the doc comment fromcontracts/engine-abi.md; implement insrc/native/nota.engine/src/nota_engine_core.cppbesidenota_engine_undo_group_end:void nota_engine_clear_undo_history(NotaEngine* e) { if (e) ENG(e)->clearUndoHistory(); } - T012 [US3] Managed interop: add
[LibraryImport(Lib, EntryPoint = "nota_engine_clear_undo_history")]ClearUndoHistory(IntPtr)insrc/managed/Nota.Infrastructure/Interop/NativeMethods.csnext tonota_engine_can_undo; addvoid ClearUndoHistory();with summary "Forget the undo/redo history; the current state becomes the baseline." to the "Undo / redo (M6-6)" block ofsrc/managed/Nota.Application/Engine/IAudioEngine.cs; implement insrc/managed/Nota.Infrastructure/Interop/NotaEngine.csbesideReset():public void ClearUndoHistory() { ThrowIfDisposed(); NativeMethods.ClearUndoHistory(_handle); } - T013 [US3] End
ProjectTemplate.ApplyDefaultwithengine.ClearUndoHistory();(FR-007) insrc/managed/Nota.Infrastructure/Persistence/ProjectTemplate.cs - T014 [US3] Extend
tests/Nota.SmokeTest/ProjectTemplateTests.cswith ABI checks: on a fresh engine add a track (CanUndo true),ClearUndoHistory()→CanUndoandCanRedofalse,Undo()returns false, the track is still there; a following edit (add an audio track) makesCanUndotrue andUndo()removes only that track. And afterApplyDefault:CanUndo == false,CanRedo == false; deleting the audio track thenUndo()restores it (FR-010) - T015 [US3] Verify the dirty-state path needs no change:
MarkProjectClean()runs after the template in bothOnMenuNew(MainWindow.Files.cs) andOnOpenedRecoveryCheck(MainWindow.Recovery.cs); if either call precedes the template, move it after
Checkpoint: All stories done — template content, undo baseline, clean state.
Phase 6: Polish & Cross-Cutting Concerns
- T016 Run the manual checks in quickstart.md in the real app with an isolated
NOTA_DATA_DIR(welcome screen off and on, File → New over a project with content, sends A/B audible, Undo no-op, no save prompt, Open existing project unchanged)- 2026-10-13: checked headlessly through the real MainWindow (harness /tmp/templateharness). With the welcome screen off, the launch workspace and File → New over a modified project both show Synth, Audio, Reverb and Delay, report nothing to undo and count as unmodified. Not checked: hearing the sends by ear, and the GUI quit prompt (it relies on the same unmodified check).
Nota closing tasks (PR gates)
- T017 Run
scripts/build.shuntil native + managed + smoke test are green- 2026-10-13: native + managed build green; all 25 template checks pass (also
--templatealone). The full run reports 2 failures, both inFilterGlideTests(EQ-8 / Dynamic EQ-8 high cut). They come from separate uncommitted work inEq.h/DynamicEq.h, not from this feature. Re-run once that work is settled. - 2026-10-13 (re-run):
scripts/build.shexit 0, SMOKE TEST PASSED, 0 failures; 25/25 template checks pass.
- 2026-10-13: native + managed build green; all 25 template checks pass (also
- T018 AGPL-3.0-only SPDX two-line header on
ProjectTemplate.csandProjectTemplateTests.cs - T019 New dependency: N/A (none)
- T020
CHANGELOG.md[Unreleased]→ Changed: "New projects start with an instrument track, an audio track and two returns — Reverb and Delay — ready to send to" - T021 FEATURES.md via the
nota-featuresskill; user manual (new project / returns pages, EN + RU) vianota-docs; shortcuts: N/A (no binding changes) - T022 Engine behaviour change → smoke test covers
nota_engine_clear_undo_history(T014)
Dependencies & Execution Order
- Phase 2 (T001–T003) blocks every story. T002 and T003 depend on T001.
- US1 (T004–T006): T004 after T001; T005 can be written in parallel with T004; T006 after T005.
- US2 (T007–T009): T007 after T004 (same method, appends after the audio track); T008/T009 extend the file from T005.
- US3 (T010–T015): T010 → T011 → T012 → T013 → T014 (each builds on the previous layer). T010–T012 do not depend on US1/US2 and can start right after Phase 2.
- Polish (T016–T022) after all stories.
Parallel Opportunities
- T005 (test file) alongside T004 (builder).
- The US3 engine/ABI/interop chain (T010–T012) alongside US1/US2 builder work — different files.
- T020 and T021 (docs) alongside T016.
Parallel Example: User Story 1
Task: "T004 Build instrument + audio tracks in ProjectTemplate.ApplyDefault"
Task: "T005 Create ProjectTemplateTests.cs with the US1 checks"
Implementation Strategy
MVP (US1)
Phase 2 → US1 → build → File → New shows two playable tracks. Undo would still remove them (US3) — acceptable for an internal checkpoint, not for the PR.
Full delivery
US1 → US2 (returns + effects) → US3 (undo baseline) → Polish. Ship as one PR: the feature is only correct with all three stories.