@gemstack/agent-data out of skill-branches; the branches SKILL.md for every place an agent wakes up

SPEC.md

@@ -3,8 +3,9 @@ The Framework: autonomous AI programming. Humans make the important decisions; c
 Six top-level pieces, one product:
 
 - `packages/framework` — the product itself, published as the npm package `framework`: one CLI (`the-framework`) that runs a foreground daemon, the agent lifecycle it orchestrates, and the browser dashboard it serves — the product's only user interface.
-- `packages/skill-branches` — the git conventions and operations behind an agent's own checkout, as an API, as the `branches` command every agent the daemon starts on its machine gets on its PATH, and as the skill (`SKILL.md`) every agent's built-in system prompt carries, published as `@gemstack/skill-branches`: the first of the skills the product is being split into. The product depends on it; it depends on nothing of the product.
-- `packages/skill-tickets` — the project's tickets and its agent queue, on the `tickets` branch of the project's own repository, published as `@gemstack/skill-tickets`: the same three faces — an API, the `tickets` command every agent the daemon starts gets on its PATH, and the skill (`SKILL.md`) every such agent finds in its checkout — over reading tickets, writing them, claiming one so two agents never work the same, and keeping the queue. The second of the skills. The product depends on it, and it depends on skill-branches for the branch it stores everything on.
+- `packages/agent-data` — a branch of the project's repository used as a file store, published as `@gemstack/agent-data`: the shared `agent-data` branch every skill keeps its files on, written through one sync → commit → push cycle that re-applies the change when the push loses a race, from a long-lived process through a persistent checkout or one-shot from any clone. A library, not a skill — read by code, never by an agent. Every skill depends on it, and so does the product; it depends on nothing.
+- `packages/skill-branches` — the git conventions and operations behind an agent's own checkout, as an API, as the `branches` command every agent the daemon starts on its machine gets on its PATH, and as the skill (`SKILL.md`) every agent's built-in system prompt carries, published as `@gemstack/skill-branches`: the first of the skills the product is being split into. The product depends on it; it depends on agent-data and on nothing of the product.
+- `packages/skill-tickets` — the project's tickets and its agent queue, on the `tickets` branch of the project's own repository, published as `@gemstack/skill-tickets`: the same three faces — an API, the `tickets` command every agent the daemon starts gets on its PATH, and the skill (`SKILL.md`) every such agent finds in its checkout — over reading tickets, writing them, claiming one so two agents never work the same, and keeping the queue. The second of the skills. The product depends on it, and it depends on agent-data for the branch it stores everything on.
 - `packages/agent-driver` — the driver seam as its own package, published as `agent-driver`: one contract for driving a coding-agent CLI as a black box — a session in a directory, one full turn per prompt, a stream of what the agent did — and the implementations for Claude Code and Codex on this device, Claude Code on a GitHub Actions runner, and a scripted fake. The product depends on it and adds the one implementation that needs the product, the hand-off to a Claude Code cloud session; it depends on nothing of the product.
 - `packages/chrome-extension` — the Claude web bridge, a companion Chrome extension: when an agent's task was handed to a Claude Code cloud session on claude.ai, it carries the question that session is parked on into the local dashboard, and types the answer picked there back into the session.
 - `packages/the-framework.ai` — the marketing website at https://the-framework.ai.

package.json

@@ -11,8 +11,8 @@
     "preview": "pnpm -C packages/framework preview",
     "dev": "pnpm -C packages/framework dev",
     "typecheck": "pnpm -C packages/framework typecheck && pnpm -C packages/the-framework.ai typecheck",
-    "clean": "pnpm -C packages/skill-branches clean && pnpm -C packages/skill-tickets clean && pnpm -C packages/agent-driver clean && pnpm -C packages/framework clean",
-    "test": "pnpm -C packages/skill-branches test && pnpm -C packages/skill-tickets test && pnpm -C packages/agent-driver test && pnpm -C packages/framework test",
+    "clean": "pnpm -C packages/agent-data clean && pnpm -C packages/skill-branches clean && pnpm -C packages/skill-tickets clean && pnpm -C packages/agent-driver clean && pnpm -C packages/framework clean",
+    "test": "pnpm -C packages/agent-data test && pnpm -C packages/skill-branches test && pnpm -C packages/skill-tickets test && pnpm -C packages/agent-driver test && pnpm -C packages/framework test",
     "========= Website": "",
     "// Develop website https://the-framework.ai locally": "",
     "website": "cd packages/the-framework.ai/ && pnpm run dev",

packages/SPEC.md

@@ -1,13 +1,14 @@
 The deliverables The Framework ships, one directory each:
 
 - `framework/` — the product: the `framework` npm package (CLI, daemon, agent lifecycle, dashboard).
-- `skill-branches/` — the `@gemstack/skill-branches` npm package: the git conventions and operations behind an agent's own checkout, with the skill's instructions (`SKILL.md`) and the `branches` command an agent follows them with: the first skill of the skills-plus architecture (#1725). The product depends on it, and so does the skill-tickets package.
-- `skill-tickets/` — the `@gemstack/skill-tickets` npm package: the project's tickets and its agent queue on the `tickets` branch of its own repository, with the skill's instructions (`SKILL.md`) and the `tickets` command an agent reads, writes and claims them with: the second skill of the skills-plus architecture (#1748). The product depends on it; it depends on skill-branches for the branch it keeps everything on.
+- `agent-data/` — the `@gemstack/agent-data` npm package: a branch of the project's repository used as a file store — the shared `agent-data` branch every skill keeps its files on — with the git runner and the exclude rule it is built on. A library, not a skill: read by code, never by an agent, so no `SKILL.md` and no command. Every skill depends on it; no skill depends on another (#1750).
+- `skill-branches/` — the `@gemstack/skill-branches` npm package: the git conventions and operations behind an agent's own checkout, with the skill's instructions (`SKILL.md`) and the `branches` command an agent follows them with: the first skill of the skills-plus architecture (#1725). The product depends on it, and so does the skill-tickets package; it depends on agent-data.
+- `skill-tickets/` — the `@gemstack/skill-tickets` npm package: the project's tickets and its agent queue on the `tickets` branch of its own repository, with the skill's instructions (`SKILL.md`) and the `tickets` command an agent reads, writes and claims them with: the second skill of the skills-plus architecture (#1748). The product depends on it; it depends on agent-data for the branch it keeps everything on, and on skill-branches for who an agent is.
 - `agent-driver/` — the `agent-driver` npm package: the driver seam — start a coding-agent CLI in a directory, prompt it for one full turn, stream what it does, resume it later — with the Claude Code, Codex, GitHub Actions and fake implementations. The product depends on it and adds its own cloud-session implementation behind the same contract.
 - `chrome-extension/` — the Claude web bridge, a companion Chrome extension that connects Claude Code cloud sessions on claude.ai back to the local dashboard.
 - `the-framework.ai/` — the marketing website.
 
-The product depends on the skill-branches, skill-tickets and agent-driver packages in code; the extension and the website depend on the product only in what they present. See the root `SPEC.md` for how they relate as a product.
+The product depends on the agent-data, skill-branches, skill-tickets and agent-driver packages in code; the extension and the website depend on the product only in what they present. See the root `SPEC.md` for how they relate as a product.
 
 ## Before modifying/creating SPEC.md files
 

packages/agent-data/DECISIONS.md

@@ -0,0 +1,41 @@
+Non-obvious decisions only, grouped by business-logic flow. Anything not listed is left
+to the implementer's judgment. Flag conflicts instead of silently deviating.
+
+## The package
+- A **library, not a skill**. A skill is a `SKILL.md` an agent reads, plus a command it
+  runs; this package has neither, because only code uses it. Skills never import each
+  other's code; this library is what every skill imports.
+- Package name = branch name: `@gemstack/agent-data` manages the `agent-data` branch, so it
+  is called the same.
+- `.branches/` holds every extra checkout of the project — each agent's, and the data
+  branch's — so its name is defined here. It starts with a dot to keep tools' `*` patterns
+  out of it: every checkout inside is a full working copy of the project. Hidden through
+  git's own exclude file, never a committed `.gitignore`: the project's files are not the
+  library's to change.
+
+## The branch
+- A branch of the project's repository holds the agents' data — tickets, the queue — like
+  `gh-pages` holds a site; code branches hold only code. Pushed and pulled on every
+  change, so every machine sees the same files.
+- One branch for all skills, each with its own folder or file on it. Not one branch per
+  skill: every extra branch would need its own checkout on disk and its own sync failure to
+  report.
+- A branch that does not exist yet is born empty, with no parent commit, so no code commit
+  is ever in its history.
+- The branch name is written once, here, as `DATA_BRANCH`; every other package imports it.
+
+## Flow: a write
+Fetch what others pushed → make the change → commit → push. If the push is rejected
+because someone pushed in between, start over on top of their changes.
+
+- A write is handed over as a small function ("add this line"), not as a finished
+  commit, so starting over is just running it again on the new files. Never a force
+  push. After two failed pushes the write reports the failure and the commit stays local.
+  The next write's fetch carries it when it still applies on top of the remote, and drops
+  it when it does not: the remote wins, only the current change runs again, and nobody is
+  told.
+- Two writers. A long-running process, the program that starts agents, writes in its own
+  checkout, `.branches/agent-data`, one write at a time. A command an agent runs writes in
+  a temporary copy of the branch, pushes, and deletes the copy; it never touches the
+  process's checkout, whose next write commits everything it finds there and resets it
+  when the write fails. A command's write that cannot be pushed fails; nothing of it waits.

packages/agent-data/SPEC.md

@@ -0,0 +1,15 @@
+A branch of a project's repository used as a file store, as an npm library: the one branch every skill a coding agent uses keeps its files on — `agent-data` — checked out once under the project's `.branches/`, written through one cycle every write goes through (sync with origin, apply the change, commit, push, and re-apply the change when the push loses a race), written one-shot from any clone, pulled eagerly, and readable from anywhere in the repository without holding a copy. The git runner and the exclude rule that machinery is built on ship with it, and so do the two names every consumer needs: the checkouts directory and the data branch.
+
+A library, not a skill: it is read by code, never by an agent, so it ships no `SKILL.md` and no command. It knows git and the filesystem, nothing else — the caller names the branch and decides what the files mean. Every skill that keeps files on the branch depends on it; no skill depends on another.
+
+## Business logic — TL;DR
+
+- **The two names** (`names`) - `.branches`, the directory every checkout of a project lives under, and `agent-data`, the shared data branch: defined once, importable without pulling in git.
+- **Running git** (`git`) - one runner with a time budget per subcommand, a timeout told apart from a git failure, the checkout a directory is in, and a push whose failure is git's own reason.
+- **Hidden from the project's git** (`git-exclude`) - a rule in git's own exclude list, never a tracked file, covering every worktree of the repository at once.
+- **A branch used as a file store** (`file-branch`) - a branch the caller names, holding files nobody edits in a working tree: born parentless or adopted from origin, checked out under `.branches/` for a long-lived process that funnels every write through one serialized cycle, written one-shot from any clone through a throwaway worktree, pulled eagerly, and readable from anywhere in the repository without holding a copy.
+- **The entry point** (`index`) - everything above in one place for a caller to import.
+
+## Before modifying/creating SPEC.md files
+
+You must always read and respect https://raw.githubusercontent.com/brillout/sdd/refs/heads/main/sdd.md

packages/agent-data/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@gemstack/agent-data",
+  "version": "0.0.1",
+  "description": "A branch of the project's repository used as a file store for coding-agent skills: the agent-data branch, checked out under .branches/, every write one sync-commit-push cycle that re-applies on a lost race — from a long-lived process through its checkout, or one-shot from any clone.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/framework/the-framework.git",
+    "directory": "packages/agent-data"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./names": {
+      "types": "./dist/names.d.ts",
+      "default": "./dist/names.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "pnpm build && tsc -p tsconfig.test.json && node --test --test-timeout=60000 'dist-test/**/*.test.js'",
+    "clean": "rm -rf dist dist-test"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^7.0.2"
+  }
+}

packages/agent-data/src/SPEC.md

@@ -0,0 +1,5 @@
+The package's source: a branch used as a file store, and the git it is built on. See the package `SPEC.md` for how the modules relate; each module's `*.SPEC.md` holds its business logic.
+
+## Before modifying/creating SPEC.md files
+
+You must always read and respect https://raw.githubusercontent.com/brillout/sdd/refs/heads/main/sdd.md

packages/skill-branches/src/file-branch.ts → packages/agent-data/src/file-branch.ts

@@ -1,5 +1,5 @@
 import { dirname, join } from 'node:path'
-import { BRANCHES_DIR } from './branch-names.js'
+import { BRANCHES_DIR } from './names.js'
 import { nodeGitRunner, type GitRunner } from './git.js'
 import { excludeFromGit } from './git-exclude.js'
 

packages/agent-data/src/index.SPEC.md

@@ -0,0 +1,5 @@
+The package's main entry point: it gathers the two names, the git runner, the exclude rule and the branch used as a file store into one place for a caller to import. No business logic of its own. The two names are also reachable on their own (`names`), for code that runs in a browser and must not pull in git.
+
+## Before modifying/creating SPEC.md files
+
+You must always read and respect https://raw.githubusercontent.com/brillout/sdd/refs/heads/main/sdd.md

packages/agent-data/src/index.ts

@@ -0,0 +1,31 @@
+export { BRANCHES_DIR, DATA_BRANCH } from './names.js'
+export {
+  type GitRunner,
+  GitTimeoutError,
+  isGitTimeout,
+  nodeGitRunner,
+  isGitRepo,
+  checkoutRoot,
+  gitReason,
+  pushBranch,
+} from './git.js'
+export { excludeFromGit, type ExcludeFs } from './git-exclude.js'
+export {
+  fileBranchPath,
+  fileBranchRepo,
+  ensureFileBranch,
+  withFileBranch,
+  pullFileBranch,
+  readBranchFile,
+  listBranchDir,
+  openBranchReader,
+  writeFileBranchDetached,
+  nodeBranchFileFs,
+  type FileBranchDeps,
+  type FileBranchWrite,
+  type FileBranchSync,
+  type CommitMessage,
+  type DetachedWrite,
+  type BranchFileFs,
+  type BranchReader,
+} from './file-branch.js'

packages/agent-data/src/names.SPEC.md

@@ -0,0 +1,11 @@
+The two names every consumer of the package builds on, defined once: `.branches`, the directory at a project's root where every checkout lives — the data branch's persistent checkout beside the agents' own — and `agent-data`, the shared data branch every skill keeps its files on, a path per skill. Both are reachable without pulling in git, so code that runs in a browser can name them too.
+
+## Rationale
+
+The directory is dotted so that tools run in the project — a type-checker's `**/*`, a test runner's glob, a formatter — never descend into the checkouts: a leading dot is what `*` does not match, and it is the one thing that keeps N copies of the repository out of every tool that does not read git's ignore rules.
+
+The branch is named here and nowhere else: every skill already depends on this package, so one exported constant is what keeps four packages from each spelling the name.
+
+## Before modifying/creating SPEC.md files
+
+You must always read and respect https://raw.githubusercontent.com/brillout/sdd/refs/heads/main/sdd.md

packages/agent-data/src/names.ts

@@ -0,0 +1,19 @@
+/**
+ * The two names every consumer of the package hangs off. Pure: no node imports, so browser-side
+ * code can name them too.
+ */
+
+/**
+ * Where a project's checkouts live: `<repo>/.branches/`, one directory per checkout, each named
+ * as the branch it is on — the data branch's persistent checkout beside the agents' own. Dotted
+ * on purpose: a `*` glob does not match a leading dot, so type-checkers, test runners and
+ * formatters run in the project never descend into N copies of the repository.
+ */
+export const BRANCHES_DIR = '.branches'
+
+/**
+ * The shared data branch of a project: the one branch every skill keeps its files on, a path per
+ * skill, checked out once at `.branches/agent-data`. Named here, once, for every consumer to
+ * import — never spelled out again.
+ */
+export const DATA_BRANCH = 'agent-data'

packages/agent-data/tsconfig.build.json

@@ -0,0 +1,6 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "outDir": "dist", "rootDir": "src" },
+  "include": ["src"],
+  "exclude": ["src/**/*.test.ts"]
+}

packages/agent-data/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "noEmit": true, "rootDir": "src" },
+  "include": ["src"]
+}

packages/agent-data/tsconfig.test.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "outDir": "dist-test", "rootDir": "src" },
+  "include": ["src"]
+}

packages/framework/SPEC.md

@@ -2,7 +2,7 @@ The product: the `framework` npm package. One CLI, `the-framework`, runs a foreg
 
 How the package's pieces relate:
 
-- `src/` — everything that runs in Node: the CLI, the daemon, the agent lifecycle (checkouts through the `skill-branches` package, gates, handoff), the drivers (the agent-driver package's, plus the product's own hand-off to a Claude Code cloud session), the `agents-logs` branch its own records live on (the tickets and the queue are the `skill-tickets` package's), autonomy (Auto PM, sweeps, CI watch), and the server side of the dashboard.
+- `src/` — everything that runs in Node: the CLI, the daemon, the agent lifecycle (checkouts through the `skill-branches` package, gates, handoff), the drivers (the agent-driver package's, plus the product's own hand-off to a Claude Code cloud session), the `agents-logs` branch its own records live on (a branch used as a file store through the `@gemstack/agent-data` package; the tickets and the queue are the `skill-tickets` package's), autonomy (Auto PM, sweeps, CI watch), and the server side of the dashboard.
 - `dashboard/` — the browser app the daemon serves: a single-page app that is a pure projection of the files the daemon writes, reading over `POST /_rpc/<name>` and a live event stream, and steering agents back through the same daemon.
 - `prompts/` — every prompt The Framework sends an agent, as markdown: the built-in system prompt, the protocols agents answer through, and the presets. The markdown is the only source of truth for agent-facing text.
 - `scripts/` — the build steps that compile the prompts into importable strings and run the package's test suites.