The data branch is agents-data, checked out under .branches/ (#1736)

[suleimansh]

Second half of #1736, in two commits:

1. The data branch is agents-data (was tf-data) and its checkout sits under .branches/ beside the agent checkouts, at .branches/agents-data. The "temporary" spelling .the-framework/branches/tf-data from The skill owns its names: .branches/ and agent- (#1736) #1737 is gone.
2. The branches skill is no longer pasted into the system prompt. The skill package links itself into every checkout it creates, where the agent's harness looks for skills — .claude/skills/branches for Claude Code, .agents/skills/branches for Codex — and the prompt's session-name step tells the agent to use it. Same mechanism for both harnesses; a new harness is one more path in the skill's list (decision in the comment below).

Hard switch, no compat. What has to happen by hand after the merge is listed at the bottom — it's a branch rename on origin, and every machine re-ensures.

🤖 curated · Fable 5, effort high

What changed

• framework-dir.ts: DATA_BRANCH = 'agents-data', DATA_CHECKOUT_DIR = '.branches/agents-data' (built from the skill's BRANCHES_DIR, via the pure @gemstack/skill-branches/branch-names subpath the dashboard already imports). The "temporary" comment is gone.
• data-branch.ts: after worktree add, the checkout dir is hidden with /.branches in git's info/exclude — the same rule the skill writes when it creates an agent checkout, added here too because the data checkout can be the first checkout a project gets. The empty root commit's message uses the constant.
• framework-gitignore.ts: the comment line in .the-framework/.gitignore names the branch from the constant.
• .the-framework/LAYOUT (tracked): data-branch: agents-data — the Cloud web runs execute the published npm build, so their bookkeeping predates repo-side renames #1575 layout gate. .the-framework/.gitignore regenerated.
• Prompts: data_branch_protocol.md (+ its SPEC, prompts/README.md, prompts/SPEC.md) say agents-data.
• Tests: hand-spelled .the-framework/branches/tf-data paths now use DATA_CHECKOUT_DIR; the branch name stays a literal where a test names the branch on purpose. install.test.ts checks the gitignore's rule lines exactly (*, !.gitignore, !LAYOUT) instead of grepping the whole file for agents, which the comment line now contains.

Commit 2 — the skill loads as a skill

• skill-branches: new skill-links.ts — linkSkill(repo, checkout) makes one symlink per harness dir (HARNESS_SKILL_DIRS = ['.claude/skills', '.agents/skills']) named branches, pointing at the package dir (its SKILL.md is the skill), each hidden via the repository's info/exclude like .branches/; best-effort, idempotent, leaves an existing entry alone. Called from settle(), so a created and a continued checkout both get it. The ./SKILL.md package export is gone — nothing reads it any more.
• framework: system-prompt.ts no longer appends BRANCHES_SKILL for an owned checkout (the non-owned fallback BRANCH_YOURSELF stays); gen-prompts.mjs no longer compiles the package's SKILL.md; the built-in prompt's session-name step now reads: "Name your branch after it: use the branches skill, which says how. Where that skill is not available, the "Branch management" section below says how instead."
• SPECs: new skill-links.SPEC.md; checkout.SPEC.md, the package SPEC.md, system-prompt.SPEC.md, prompts/SPEC.md, prompts/system_prompt.SPEC.md, FEATURES-SPEC.md say the skill is the checkout's, not the prompt's.

Dogfood — does the agent actually pick the skill up?

Yes. A throwaway repo with a local bare origin, an isolated daemon built from this branch (XDG_CONFIG_HOME rig, port 4201), one local Opus run, handoff: local:

• The checkout came with both links: .claude/skills/branches and .agents/skills/branches → the package; info/exclude holds /.branches, /.claude/skills/branches, /.agents/skills/branches; git status --porcelain in the checkout was empty.
• The agent's transcript, in order: "Let me check the branch naming convention." → Skill {"skill": "branches"} → Bash "branches name add-farewell" → {"ok":true,"branch":"agent-add-farewell"} → the edit → a commit → branches status → done. The run's branch event carries sessionName: "add-farewell"; the checkout's branch is agent-add-farewell.
• Commit 1 in the same run: the daemon created .branches/agents-data from nothing, linked tickets into it at the root, and pushed agents-data to the remote.

Codex was not run (no Codex login on this machine); its side is the same symlink to the same file, in the directory its docs name.

Proof: skill-branches 117/117, framework 1471/1471, dashboard 864/864, typecheck clean.

SPEC changes

packages/framework/src/framework-dir.SPEC.md — the "temporary" paragraph is gone, the intro names the place:

-Names `.the-framework/` — ... — and the data branch, `tf-data`, with the place its checkout sits under a project. Kept on its own so browser-side surfaces ...
-
-The data checkout's place, `.the-framework/branches/tf-data`, is temporary (#1736): the agent checkouts moved to the `skill-branches` package's `.branches/`, and the data checkout stays where it has always been until the convention for where a data branch lives is decided.
+Names `.the-framework/` — ... — and the data branch, `agents-data`, with the place its checkout sits under a project: `.branches/agents-data`, beside the agent checkouts and named as its branch like each of them. Kept on its own so browser-side surfaces ...

packages/framework/src/data-branch.SPEC.md — rename only, 5 lines; the two that carry the path:

-- **Its checkout, and the roadmap shortcut** - the branch is checked out under `.the-framework/branches/tf-data`, and the repo root gets a `tickets` link into it that git is told to ignore.
+- **Its checkout, and the roadmap shortcut** - the branch is checked out under `.branches/agents-data`, and the repo root gets a `tickets` link into it that git is told to ignore.
-The branch is checked out at `.the-framework/branches/tf-data`, named after its branch like every other checkout there. ...
+The branch is checked out at `.branches/agents-data`, named after its branch like every other checkout there. ...

packages/framework/prompts/data_branch_protocol.SPEC.md (7 lines), packages/framework/src/SPEC.md, packages/framework/prompts/SPEC.md, SPEC.md, FEATURES-SPEC.md (1 line each): tf-data → agents-data, nothing else.

After the merge — by hand

Once, on origin (the branch rename; the daemon never renames a branch):

git fetch origin
git push origin origin/tf-data:refs/heads/agents-data
git push origin --delete tf-data

On every machine that ran the framework in this repo, after pulling main:

git worktree remove --force .the-framework/branches/tf-data
rm tickets                      # the root link points into the old checkout
git branch -D tf-data

then start the daemon: it creates .branches/agents-data from origin, re-links tickets, and writes the /.branches exclude.

Known consequence, on purpose: framework@0.7.0 on npm still writes data-branch: tf-data, so the layout gate (#1575) refuses that build in this repo from the merge on — cloud runs that install from npm are blocked until the next publish. The publish is held anyway until the skill packages are reviewed.

[suleimansh]

Next commit here drops the inline skill from the system prompt: the agent gets branches as a real skill instead.

How it gets there: the skill itself puts a symlink into every checkout it creates, one per harness — .claude/skills/branches for Claude Code, .agents/skills/branches for Codex — pointing at the package's SKILL.md, hidden via info/exclude like .branches/ itself.

Why this way: it works the same for both harnesses (same file, same mechanism, no per-harness code in the daemon), and a new harness later is one more path in the skill's list. The alternative — the daemon passing --add-dir to Claude and doing something else for Codex — would be two mechanisms for one skill.