The .sfab directory

Every repo the factory manages gets a .sfab/ directory: a read-only mirror of the platform's tasks and documents, committed like any other code so agents working in a sandbox (and humans browsing GitHub) can read project state straight from the filesystem.

.sfab/
  .docs/
    README.md
    architecture/
    decisions/
    ...
  .tasks/
    INDEX.md          # auto-regenerated, grouped by status
    ALW-42.md         # one file per task, status in frontmatter
    ALW-43.md

The dot-prefix rule

Directories inside .sfab/ that start with a dot are platform-owned: the platform database is the source of truth, and the sync overwrites local edits.

Don't edit .sfab/.tasks/* or .sfab/.docs/* by hand or in a PR; your change will be silently clobbered on the next sync. To read or write tasks and documents, go through the platform UI or the MCP tools (tasks_*, documents_*); the repo mirror catches up on its own moments later.

Tasks: flat files plus an index

Tasks sync to .sfab/.tasks/<id>.md with the status in YAML frontmatter, not in the path, so a status change is a one-line edit, paths stay stable for anything linking to them, and git history stays clean. The at-a-glance view lives in INDEX.md, regenerated on every sync and grouped by status: one cat .sfab/.tasks/INDEX.md shows the state of the whole repo.

Documents: free-form

.sfab/.docs/ has no enforced structure. Authors (human or agent) decide where each document lives, and whatever organization emerges, emerges. Architecture notes, decision records, plans: it's all markdown, versioned with the code it describes.

Repo-scoped, project-grouped

Tasks and documents belong to a repository, not a project. A project is a thin grouping, a set of repos one agent team operates over, with no content of its own. Work that spans repos is split into per-repo tasks explicitly, so every task maps to one repo, one PR, one CI run, one merge gate.