loswfx: what it is, where it is, where it's going

what loswfx is

loswfx is an autonomous software factory built around openai-compatible providers. it runs as a single go binary, owns the kernel, and treats every model provider as an adapter behind a thin contract. an operator runs loswfx work <id> from a target project; the kernel picks the next phase, dispatches an agent capability against a configured provider, captures every meaningful state change in an append-only ledger, and ships a typed receipt for every attempt. cli, http api, and a native bubbletea tui all project from the same read models.

it is the provider-switching evolution of the loswf (lights out software factory) initiative. loswf v1 and loswf2 remain the anthropic-native sibling line; loswfx exists to keep the workflow core durable across the entire openai-compatible adapter family — openai, openrouter, ollama, lm studio, ollama cloud, and a self-hosted litellm proxy for non-openai-shaped providers (anthropic, gemini, bedrock). one adapter shape, every provider.

the goals it was built around

loswfx optimizes for a short list — written down at milestone one and held since:

• provider portability — no provider-specific orchestration branching in the kernel. new providers add a config profile, not a code path.
• durable, replayable workflow execution — every state change is a ledger event; a crashed run reconstructs from the events file.
• explicit state transitions — work items move by ledger entry, not by chat-transcript inference. nothing reads agent conversation history as memory.
• bounded, observable feedback loops — every attempt produces a receipt with parameters, cost estimate, exit code, and content hashes.
• local-first operation — the system runs entirely on a developer laptop with a fake or local provider. no cloud dependency in the kernel.
• first-class control over sandboxing, mutations, credentials, and audit — the host agent harness is an adapter, not the runtime foundation.
• minimal dependency on any one agent host — claude code, codex harness, crewai, pi, langgraph can all be useful execution surfaces; none of them owns workflow semantics.

what loswfx deliberately does not optimize for: slash-command parity with any specific runtime, copying claude or codex workflow assumptions into core, making every model api look supported when it needs special orchestration, or anchoring the architecture on a sandbox the kernel can’t audit. the guiding principle from the team note: distinguish model quality from harness suitability.

where it is now

49 milestones complete as of today. the v0.4.0 release tagged this afternoon ships two parallel arcs landed since v0.3.3 — 114 commits — and the third arc just opened with m49.

the orchestrator trustworthiness arc ran from m41 through m48. it grew the cardinal-practices catalog from 7 validators to 12, scripted all 12 promoted tandem and onboarding phases end-to-end under a hermetic provider that needs no api credits, activated every previously-pending proof_* scenario in the test suite, and added a soft-warning dimension so validators can surface drift without breaking ci. the arc closed cleanly in m48 with the four owed carry-forward items landed — agent-loop unit test, flag-registry discovery, 23 historical tracking docs canonicalized, and a contributing.md guide for proof_* authoring. closeout-on-acceptance reports zero schema warnings.

the native skill support arc ran in parallel. skills became a first-class layer: 27 skill markdown files live next to 8 tool primitives under .loswf/tools/. brand voice flows automatically through both image generation (design.md §9) and remotion video authoring (design.md §10); brand pronunciation is machine-consumable from design.md §12, which is why the article you might be hearing reads “low swiff” instead of the unfortunate alternative the tts wanted to produce. a new cardinal practice (illustrated-planning, the 12th validator) nudges planning artifacts toward inline diagrams. bin/loswf-devlog publish ships posts direct-to-main on the devlog repo without an editor pr dance — including this one.

the practical artifacts of these arcs: 12 cardinal practices the team is now structurally accountable to, 27 skills the kernel can dispatch against, 8 tool primitives that emit uniform receipt jsons, six embedded architecture diagrams in the doc set, two demo remotion compositions that render brand-aligned video on every push, and a four-second-to-eight-second visualization of a work item moving through the workflow.

the phase shape above is what the kernel actually does. an operator-submitted work item enters intake; the sweep selects it for triage; a capability decomposes (when the work item is large) into child items, or the work item moves directly through plan to build to review. review can route back to build (rework) or back to plan (scope change). both ship and escalation are terminal. every transition is a ledger event; every attempt is a receipt; every receipt threads through runid / attemptid / traceid / receiptpath correlation ids so the trace command reconstructs the chain.

how it works

a single capability is one file in internal/workspace/ — capability_triage.go, capability_plan.go, capability_build.go, capability_review.go — satisfying a capability interface composed of five smaller interfaces (named, promptsource, toolsource, payloaddecoder, sideeffectapplier). the kernel doesn’t know what any specific capability does. it asks for the prompts, runs the provider tool loop, asks the capability to decode the result, and asks it to apply side effects. adding a fifth capability is one new file and a register call, not a switch-statement edit across seven files.

the cardinal practices catalog runs against any workspace via loswfx practices check. the 12 validators today: tdd-coverage, truthful-status, shadow-persistence, skill-frontmatter, customer-feedback-first-class, engagement-init-reproducible, feature-coverage, flag-coverage, phase-name-coverage, skill-name-coverage, closeout-on-acceptance, illustrated-planning. each refuses to let a workspace drift from the practice. the operator’s own work is the system under test; the catalog runs on every push.

the skill / tool pairing pattern is the agent devops surface. recurring agent plumbing becomes a deterministic cli or python primitive plus a sister skill that documents when to invoke. image generation lives at .loswf/tools/generate_image.py paired with skills/image-generate/. article audio: .loswf/tools/generate_article_audio.py paired with skills/article-audio/. remotion: three skills (remotion-render, remotion-author, remotion-with-image) paired with two tools (render_remotion.py, lint_remotion_spec.py). when a workflow runs three times, it’s worth codifying. the pattern keeps the kernel small at the center and extends cleanly at the edges.

what makes it different

three structural decisions distinguish loswfx from anything that looks like an agent framework wrapper:

the ledger is the only memory. state lives in events.jsonl plus a sqlite mirror. nothing else reads chat history as truth. a crashed run reconstructs from the file system. a multi-engagement debug session opens json files in an editor. the audit surface is the disk, not a tracing service.

provider portability is structural, not aspirational. there is one openaicompatibleadapter in internal/provider/ that reaches every supported provider. the kernel does not branch on provider quirks. the litellm gateway profile (per adr 0004) handles non-openai-shaped providers without polluting the kernel. when a new provider lands, the change is a config profile.

practices are validators, not aspirations. the cardinal-practices catalog grew because the team learned a hard lesson early — documented-only practices get abandoned under pace pressure. enforced ones survive. the catalog is the team’s authoritative statement of how it writes code; loswfx practices check prints it.

these three together describe a system that’s debuggable from a directory listing, portable across the model landscape, and structurally honest about its own engineering discipline.

trajectory

m50 through m54 sit in docs/MILESTONE-*-PLANNING-DRAFT.md. the immediate-next arc is in flight:

skill contract formalization (m49 → m50). m49 landed today: docs/SKILL-CONTRACT.md pins the schema, the role-contract validator armed as the 13th cardinal practice, and eight pilot skills now carry machine-parseable contract: frontmatter (engagement-plan, iteration-plan, repo-audit, product-brief, retrospective, research-brief, research-design-implications, triage-decomposition). the remaining 19 skills surface as soft warnings pending m50, which extends the schema with a kind: marker for methodology-only skills, migrates the remainder, retires the soft-warning dimension, and builds the edit-source detector that promotes recurring operator revisions into candidate skill-prompt changes.

operator ergonomics (m51). three new cli commands surfaced from data the system already records but currently requires the operator to reconstruct by hand: loswfx health aggregates the practices catalog into a single screen; loswfx skills list surfaces the skill catalog from frontmatter; loswfx cost reads receipts and reports rolling totals by service.

three-slice dashboard (m52–m54). the native tui evolves into a dashboard. m52 ships the spine — cross-engagement health table with drill-down into the existing single-engagement panels. m53 adds a persistent chat surface for foreman prompts so the operator never leaves the tui. m54 adds activity visualization — sparklines per engagement, cost-over-time, practices-drift-over-time. all ascii and unicode in the terminal; no external graphics library.

each arc is independently shippable. the contract arc compounds — its frontmatter data shape powers the operator commands and the dashboard’s skill listings. the dashboard arc ships on top of the contract metadata. the team will land them in the listed order.

loswfx will keep growing the catalog, the surface, and the trajectory; it will not start to look like a framework. the kernel stays small. the operator stays in control. the model is just another adapter behind a thin contract. forty-eight milestones in, the shape that worked at milestone one still works.