Project Task Overrides

Project task overrides

The shipped task shape — ## Why, user stories, acceptance criteria, RICE, the standard fields — is a sensible default, but no default fits every team. A project can shadow it by dropping one file into its brain: _dream_context/overrides/task.md. Discovery is purely by file presence — absent the file, every consumer is byte-identical to the shipped defaults, so existing projects regress by exactly zero. The override lives inside the brain, so it survives dreamcontext update and travels with the repo. A malformed override is surfaced as doctor warnings, never silently ignored and never fatal to task creation or sync.

The file carries two things at once. Its frontmatter custom_fields: declares a field schema — each entry has a name, a type (text / number / select / date), an optional key (the stable id; defaults to the snake_cased name, so a rename keeps the same id), options for a select, sync targets (clickup / github, both by default), and an optional prompt that tells the agent how to fill the field. A field may also be marked required: true — which hard-fails tasks create, complete, and any status move to completed/in_review until the field is set (or --allow-missing-required is passed), and renders ⚠ UNSET (required) until filled — or ask: true, which tells the agent to ask the user for the value rather than ever fabricating one (in an autonomous context like sleep, where there is no user, the field is left unset and flagged instead). Its body is the task template the CLI scaffolds from, plus an optional ## Agent Instructions section that is stripped from scaffolded tasks and read by agents at runtime.

Field values are set with dreamcontext tasks create … --field team=platform --field story_points=8 or, on an existing task, dreamcontext tasks field <slug> <key> <value> (clear to unset). Values are validated against the schema — select options are enforced, numbers coerced — and stored under a custom_fields: map in the task's frontmatter. Each task's set values surface inline — in the snapshot's Active Tasks block and in tasks list --long — so the agent and the human both see them without opening the file. They then ride the same sync engine as everything else: on ClickUp a select becomes a native drop-down and the rest become native list custom fields; on GitHub a select becomes a <key>:<value> label and the rest land in a human-readable <!-- dc:fields --> block in the issue body. dreamcontext tasks provision (or the dashboard's two-step preview) creates whatever is missing on the remote and reuses fields/labels that already exist by name instead of duplicating them.

The piece that makes this more than a data schema is the agent briefing. When an override is active, the same rendered briefing is injected into both the SessionStart snapshot (the main agent) and every sub-agent's context — listing each custom field, its allowed values, and its prompt, plus the verbatim Agent Instructions. So the project's task format isn't just enforced at write time; the agent is told, every session, what shape a task should take and how to fill each field. The schema and the instructions stay in one file, version-controlled, and the dashboard's Settings panel edits the very same file the agent reads.

Dates and assignees

Two more v0.9.1 refinements round out the task model. A task now has an optional date range — a planned start and a due/end — each independently settable or clearable (tasks start / tasks due accept a clear sentinel; tasks create takes --start/--due). Start must be on or before due; an inverted range is rejected at the CLI, the server route, and each backend adapter. The range is wired to the backlog convention: setting either date removes the backlog tag (a dated task is planned, not backlog), and adding backlog clears both dates. The first time a task moves to in_progress its start_date is auto-stamped with today if still unset — an explicitly planned start is never overwritten, and no other transition stamps. Both dates sync natively to ClickUp's start/due fields and ride a <!-- dc:dates --> block in the GitHub issue body (composed above the prose and stripped before the 3-way prose merge, so it never contaminates the human-readable diff). The dashboard's Timeline (Gantt) and Calendar views consume the range for bar width and positioning.

Assignees resolve to real people. Earlier, a person:<slug> tag that matched no ClickUp member silently fell back to the API-token owner's account — a quiet, wrong assignment. Now, on a cloud backend, --person <name> and tag person:<slug> resolve the name through a pure, provider-generic matcher (member-match.ts) against the live roster: an exact match wins, a diacritic-folded fuzzy match on display name or first name follows, an ambiguous name aborts with the candidate list so you can be specific, and an unmatched name is recorded but warns that it won't sync until that person is a member. The push path is a second safety net — unmapped slugs are split out and appended to SyncReport.warnings[], surfaced loudly in sleep done and tasks sync. An assignment is never silently dropped or reassigned. In the dashboard, the picker offers only real roster members on a remote backend, and any non-member chip already on a task is flagged with a red "won't sync" warning.

---

Part of the dreamcontext deep dive — Home · README