Skip to content

RFC-0001: v0.1 implementation plan

Status: Implemented Author: Alex Nodeland Created: 2026-09-28 Discussion: accepted alongside the architecture (ADR-0001 to ADR-0013)

Summary

Build artifactr v0.1 as described in the architecture, in eight phases. Each phase lands on main as one or more small pull requests that keep main releasable (ADR-0014) and pass every quality gate (ADR-0015). This RFC is the tracking document for that work.

Motivation

The design is accepted but only exists on paper. A shared plan lets each pull request be reviewed against a known destination, keeps the order of work dependency-driven (nothing builds on an unsettled API), and gives one place to see progress.

Design

Order of work

Each phase depends only on the phases before it:

Phase Deliverable Exit criteria
0. Foundation Packaging, tooling, CI, contribution and design process, license CI green on the empty package at 100% coverage
1. Core artifactr.core: ids, actors, artifact types and registration, patches, commands, events, envelopes, proposals, rejections, and the pure rules commit, respond, change_notes, resume Conformance fixtures cover every command and rejection; patch round-trips are property-tested
2. Workspace artifactr.workspace: storage protocols, Workspaces, Workspace, run leases, history store, in-memory storage The workspace behaviour suite passes against in-memory storage
3. Agent artifactr.agent: Session, the ArtifactWorkspace capability, generic tools, change notes, steering, deferred pauses, live output Scripted runs with TestModel and FunctionModel assert the events written for every hook
4. SQL artifactr.sql: SQLAlchemy 2 async storage and Alembic migrations The workspace behaviour suite passes against SQLite and PostgreSQL
5. Surfaces artifactr.fastapi (WebSocket thread protocol and REST) and artifactr.mcp; the protocol JSON Schema Contract tests for every frame and command; an MCP client round-trip; schema drift is checked in CI
6. Reference implementation examples/docplan: Doc and Plan types, tools, a runnable app, and the CLI Smoke-tested end to end with a scripted model
7. Docs site and brand Documentation website with guides and API reference; brand assets; branded README The site builds in CI with no warnings

Package layout

src/artifactr/
    __init__.py        # the common public API, re-exported
    core/              # pure rules; depends on pydantic and jsonpatch only
    workspace/         # scoped handles, storage protocols, in-memory storage
    agent/             # the pydantic-ai capability, Session, live output
    sql/               # extra: SQLAlchemy storage
    fastapi/           # extra: WebSocket and REST
    mcp/               # extra: MCP server
tests/                 # mirrors src/; conformance fixtures under tests/conformance/
examples/docplan/      # the reference implementation
schemas/               # generated protocol JSON Schema

The layering in the architecture is enforced by imports: core imports nothing else from artifactr, workspace imports only core, and so on up.

Removing the prototype up front

ADR-0013 planned to remove the prototype once the reference implementation reached parity. This plan removes it in phase 0 instead:

  • its test suite already fails on main, and trunk-based development requires main to be green from the first pull request
  • it occupies the artifactr package namespace the new layout needs
  • it was never functional as a whole (for example, its MCP server registered no tools), so there is no working behaviour to reach parity with

Its interactive CLI is the one piece worth keeping. It stays in git history and is ported in phase 6.

Drawbacks

  • Until phase 6 there is no runnable application in the repository, only the library and its tests.
  • Phases 1 to 3 settle most of the public API before any real client exercises it. The reference implementation may force API changes late in v0.1.

Alternatives

  • Vertical slices (one feature through every layer at a time) would produce a runnable app sooner, but every slice would reopen the core API while it is still moving.
  • Keeping the prototype until parity was the original plan; see above for why it was dropped.

Unresolved questions

  • ~~How change notes are delivered into a live run.~~ Settled in phase 3: as a user-prompt part wrapped in <workspace-changes> tags (ADR-0020).
  • ~~How long command ids are remembered for deduplication, and where.~~ Settled in phase 5: per process, the most recent 10,000 by default (ADR-0022).
  • The snapshot format for resuming after retention. Deferred beyond v0.1 unless phase 5 needs it.

Tracking

  • Phase 0: foundation
  • Phase 1: core (ADR-0018 records the host contract)
  • Phase 2: workspace (ADR-0019)
  • Phase 3: agent (ADR-0020)
  • Phase 4: SQL (ADR-0021)
  • Phase 5: surfaces (ADR-0022)
  • Phase 6: reference implementation (ADR-0024; it forced four small API fixes, as the drawbacks anticipated)
  • Phase 7: docs site and brand (ADR-0023)