Effort model — the unit of work

The effort is the unit of work for building TED OS, and GitHub is the single source of truth. The effort schema is also a training-trace dataset schema — every field below is also a training column (ADR-006; see Decisions).

The unit

1 effort = 1 parent issue · 1 branch · 1 worktree · 1 PR. No forced tiny PRs — big effort-PRs are fine while building. One effort decomposes into N native GitHub sub-issues (parallel or sequential, decided at scoping).

parent issue #N  ──►  effort/<N> branch + worktree (from develop)
   ├─ sub #a ─► sub/<N>a worktree (from effort/<N>)  ─┐
   ├─ sub #b ─► sub/<N>b worktree                     ├─ merge into effort/<N>
   └─ sub #c ─► sub/<N>c worktree                     ┘
effort/<N>  ──►  ONE PR ──►  develop

Sequential efforts may commit sub-issues directly on the effort branch (one commit per sub-issue — that commit diff is the sub-issue's training patch). Parallel sub-issues use their own, file-disjoint worktrees and merge in.

The parent issue IS the plan

There are no MDX plan files (the requirement is retired). The parent issue body is the plan, using four sections that map 1:1 to dataset columns:

Section	Maps to
Goal	problem statement
Scope	the plan (the sub-issue DAG; each marked parallel / sequential)
For agents	retrieval context — exact file paths / entry points
Verification	the label / reward (commands, checks, acceptance)

Strategy / roadmap narrative lives in the repo's knowledge/; the "where we stand" view is generated from GitHub issue data — see the Plan Engine (/plan · /roadmap · /work).

Lifecycle

Step	What
new	a parent issue (the template) + native sub-issues
start	an effort/<N> branch + worktree; board → In Progress
orchestrate	sub-issues in their own worktrees (file-disjoint) → merge into the effort branch
pr	one PR effort/<N> → develop (rich body + a ## For agents section)
close	merge → close the parent + subs → board Done → snapshot sub-diffs before squash → prune

Board + plan state are correct by construction — the close op owns them, not a separate "mark done" step.

Branch naming

<kind>/<issue-number>-<slug> — kind ∈ feat fix task chore security scaffold ci adr spike plan. An effort uses effort/<N>-<slug>; its sub-issues use sub/<N><letter>-<slug> (which never open their own PR — they land in the effort branch).

Why it doubles as training data

The dev workflow (goal → plan → patch → verify → outcome) is exactly a builder-agent trajectory dataset. Per-sub-issue diffs are snapshotted before squash (squash would destroy the per-step pairs); outcome labels come from the result (merged = positive · abandoned/reverted = negative) plus a manual gold flag for exemplars. Secrets are scrubbed and tenant/client data never enters the corpus — see Decisions (ADR-006/007).