Roadmap: Gas Town adoption — pure- beads, Python BeadStore adapter, MCP bead exposure

[ojfbot]

Parent RFC

ojfbot/core#15 — RFC: Frame × Gas Town

Purefoy's scope

Purefoy is a Python repo (knowledge base about Roger Deakins cinematography). Its Gas Town adoption is distinct because it's Python, not TypeScript. The priorities are: (1) adopt the FrameBead shape in Python/Pydantic so it's structurally aligned, (2) implement a Python BeadStore, (3) expose beads over the MCP server so other Frame agents can consume Purefoy's knowledge as beads.

Dependency: ADR-0009 (FrameBead) must land in core first — Purefoy implements the same shape in Python.

---

Sprint 1 — FrameBead in Python (pure- prefix)

• FrameBead Pydantic model — same shape as the TypeScript type, implemented in src/models/bead.py

  class BeadType(str, Enum):
      adr = 'adr'
      task = 'task'
      agent = 'agent'
      # ... etc
  
  class FrameBead(BaseModel):
      id: str           # "pure-abc12"
      type: BeadType
      status: BeadStatus
      title: str
      body: str         # markdown
      labels: dict[str, str]
      actor: str
      hook: Optional[str] = None
      refs: list[str] = []
      created_at: datetime
      updated_at: datetime
      closed_at: Optional[datetime] = None

• pure- prefix — Purefoy beads use this prefix
• Python FilesystemBeadStore — reads/writes JSON to .beads/pure/ (same directory convention as TypeScript implementation)
• Existing leaf models (Topic, Technique, Film, Quote) wrapped as FrameBeads on load

Acceptance criteria

GET /api/beads?type=task returns Purefoy knowledge items as FrameBeads. Beads written to .beads/pure/ as JSON files. Python BeadStore is structurally compatible with the TypeScript BeadStore interface.

---

Sprint 2 — AgentBead (Python)

• AgentBead Pydantic model — extends FrameBead with role/app/status/hook labels
• purefoy witness AgentBead — pure/witness-001 created on first agent init
• prime pattern — Python equivalent of primeNode: check hook on startup, route to work if found

---

Sprint 3 — MCP bead exposure

• MCP server exposes beads — existing MCP server gains list_beads(filter: BeadFilter) and get_bead(id: str) tools
• Other Frame agents can query Purefoy's knowledge base as beads via MCP
• Bead IDs in MCP responses — all MCP tool responses include bead_id for cross-referencing
• Core-reader integration — CoreReader can display pure- beads in its search/activity feed once A1 is adopted cluster-wide

Acceptance criteria

cv-builder agent can call the Purefoy MCP server and receive pure- FrameBeads about cinematography techniques. The bead shape is identical to what cv-builder uses for its own beads.

---

Sprint 4 — kb-expansion molecule

• kb-expansion.toml formula — steps for expanding the knowledge base: identify_gaps → research → validate → ingest → index
• Python molecule runner — Python equivalent of molecule-compiler.ts; translates formula steps into a sequential Python agent workflow
• Checkpoint recovery — uses .beads/pure/ to persist step completion

---

Documents required before Sprint 1

• ADR-0009: FrameBead (core — must land first)
• domain-knowledge/gastown-context.md (core)

Open question: Python BeadStore compatibility

The TypeScript BeadStore interface and the Python FilesystemBeadStore should write to the same directory format (.beads/<prefix>/YYYY-MM/bead-id.json). Verify the JSON schema is identical before Sprint 1 ships. If format diverges, cross-app search breaks.

Run /gastown audit to check current state