You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Facility currently treats agent work as a sequence of short-lived runs. A run gets its own sandbox, produces a controlled delivery, and then ends. Conversations, previews, permissions, receipts, budgets, and agent definitions have separate lifecycle rules.
Today, a contributor who works across several runs has to reconstruct the environment and execution context. A contributor should be able to start from an issue, work for several days, run the whole application, ask another agent to continue, and inspect the result from a browser without rebuilding context on every turn.
Facility 0.12 will use a persistent workspace as the home of the work. The story, conversation, engine sessions, Git worktree, development services, and preview all refer to that workspace.
This is a breaking product change. We will build the replacement path, verify it, migrate the useful agent workflows, and remove the old run and receipt machinery before the release.
Product behavior
A user starts or opens a story from MCP or the Facility UI. Facility creates one durable workspace for it. The compute can sleep and can be replaced after a failure. The attached storage keeps the Git worktree, uncommitted changes, installed dependencies, local service data, and Claude Code or Codex session files.
The workspace can run the repository's development environment. Projects may use Docker, Docker Compose, setup scripts, seed data, and browser tests. Declared ports are available through an authenticated preview URL, so a person can test the running branch from another computer.
The same conversation is visible to every authorized project maintainer. A maintainer can send another message, choose another configured agent, or switch between the UI and an MCP client. Facility records which agent, engine, model, and manifest revision handled each turn.
Merge and archive change the story's status. They may put the compute to sleep. They do not delete the engine sessions, worktree, volume, conversation, or artifacts. Facility removes durable state only after an explicit delete action from an authorized user.
Agents as code
Every agent is configured in the repository under .agents/. The file contains Markdown frontmatter and a prompt body. One parser and schema serve kickstart, the control service, MCP, the scheduler, and the UI.
The initial kickstart crew contains:
architect
builder
pr-reviewer
address-review
ci-doctor
security-audit
Each file declares its engine, model, optional reasoning effort, enabled state, and triggers. Triggers may be manual, MCP, UI, GitHub events, or a schedule. Teams can add another agent by adding another file that follows the same schema.
The server treats these names as data from the manifests. Model configuration lives in the repository file. A codex-builder, for example, is an ordinary agent file whose engine is Codex and whose model is named in that file.
The agent schema rejects permission, sandbox, tool allowlist, and similar fields.
Access model
All configured agents get the same access:
full shell, filesystem, process, network, Docker, browser, and tool access inside the story workspace
full maintainer access to every repository connected to the project
An architect, reviewer, scheduled audit, and interactive builder receive the same project capability. Facility has no read-only agent mode.
The remaining boundaries protect Facility users from each other and protect the control plane. Authentication, project membership, tenant and workspace isolation, secret handling, signed webhooks, preview authentication, and branch protection still apply. Facility issues short-lived GitHub credentials with the project's full maintainer capability for every agent and action.
Scheduled and event-driven work
Scheduled agents remain part of Facility. The scheduler reads the same .agents/ files as manual execution. A trigger posts a new message to a persistent story and dispatches a turn.
PR review and CI repair reuse the story attached to the pull request. A recurring project task such as security-audit gets a stable story, conversation, worktree, and set of engine sessions. Editing or disabling a schedule stops future turns and leaves its existing state intact.
The dispatcher must deduplicate retries and concurrent scheduler replicas. Ordinary idempotency records replace receipt chains and the separate watchtower pipeline.
Recurring story identity uses project, manifest name, and trigger identity. Renaming name creates a new recurring story. Removing or disabling the file leaves the old story available, and restoring the same name and trigger reconnects to it.
MCP and UI
MCP is the main interface for coding agents and automation. Its public tools cover projects, configured agents, stories, conversation, environment status, preview access, suspension, archive and restore, and explicit workspace deletion.
The Facility UI stays in the product. It covers the same work for a person: project setup, the .agents/ catalog, model and trigger configuration, stories, attention, conversation, service status, logs, preview, archive and restore, and workspace deletion.
Both interfaces call the same application services. MCP is hosted by the control service. Editing an agent in the UI changes the repository file through Git, which remains the source of configuration.
Storage and lifecycle rules
The following data survives compute suspension and replacement:
the Git worktree, including untracked and uncommitted files
every native Claude Code and Codex session associated with the workspace
conversation messages and turn records
local development data stored on the workspace volume
links to commits, pull requests, reports, screenshots, and other artifacts
Idle time and merge may suspend compute. Archive is reversible. These events leave durable storage intact.
An explicit workspace deletion stops compute, revokes previews, and removes the durable volume and native session files. Story messages, turn metadata, pull request links, and lightweight artifact records remain as history. The UI and MCP response must state this boundary before the request is accepted. The operation is authorized, idempotent, and isolated to one project and workspace.
Work included in 0.12
The sub-issues attached to this epic cover:
the .agents/ format and kickstart output
durable workspace and storage adapters
the story, conversation, session, and turn model
native Claude Code and Codex execution
the common trigger dispatcher and scheduler
full maintainer GitHub access for every agent
Docker or Compose environments, browser testing, and authenticated previews
the MCP contract
the maintained Facility UI
removal of the old run, receipt, proposal, model gateway, and separate preview paths while retaining cost and budget controls
project cost accounting and monthly budget preflight enforcement
operational insights, audit history, and delivery analytics in the existing control plane
the project-scoped GitHub issue, pull request, and CI mirror
the AWS control-plane reference deployment with Vercel workspaces
migration checks, end-to-end tests, pilot use, and the 0.12 release
Scope excludes a hosted agent marketplace, per-agent permissions, a separate model or budget gateway, receipt verification, public previews, and a permanent compatibility mode. Monthly project budget enforcement remains part of the control plane. Preview access is limited to authenticated maintainers of the project.
Delivery approach
The replacement is being implemented as the Facility 0.12 path in draft PR #289. It uses one data model and does not maintain a permanent switch between old runs and story workspaces. Old services, tables, queues, and packages are removed only after their required behavior has a replacement test.
Provider, runtime, authentication, preview routing, multirepository behavior, agent-file writes, project secrets, and storage decisions are recorded under apps/docs/docs/reference/decisions/ with evidence from a working fixture. The fixture contains an application, an API, a database, seed data, a browser test, and more than one configured agent.
Existing 0.11 operational history will not be migrated into the new workspace schema. Startup against a 0.11 database stops without modifying it. The release work documents backup, export, clean installation, and full 0.11 rollback.
Changes to authentication, project scoping, GitHub credentials, secrets, webhooks, or preview access require unit and deterministic integration tests. These tests must cover valid use, malformed input, expired and revoked credentials, replay, and cross-tenant denial. The default suite cannot require live credentials or network access.
Completion criteria
Kickstart writes the standard crew to .agents/, with an explicit engine and model in every file.
A contract test loads each standard agent through kickstart, API, MCP, scheduler, and UI and produces the same normalized hash.
Manual, GitHub, UI, MCP, and scheduled triggers run through the common dispatcher.
After compute replacement, untracked files match byte for byte, the dependency tree remains present, and the native session resumes.
The reference fixture's application, API, database, seed data, and browser flow work through an authenticated maintainer preview.
Every agent can create branches, commits, pushes, issues, comments, checks, workflows, and pull requests with project maintainer access.
Merge and archive create no storage deletion job, and a later wake resumes the same worktree and session.
Idle, merge, archive, disabled schedule, and failed turn tests create no storage deletion; the explicit delete command removes one chosen volume.
MCP and UI both pass the release sub-issue's full end-to-end scenario.
Auth, GitHub credential, webhook, tenant, and preview integration tests cover malformed, expired, revoked, replayed, and cross-tenant inputs.
The old run, receipt, HITL proposal, model gateway, database-backed agent definition, and separate preview paths no longer ship.
Turn usage and model cost are stored once per turn, and monthly project budgets block new turns before provider invocation.
Monitoring, delivery analytics, audit history, and the GitHub issue, pull request, and CI mirror remain available through MCP, API, and UI.
The reference deployment runs the control plane in AWS and story workspaces in Vercel.
A clean 0.12 installation and the documented 0.11 rollback procedure have been tested.
The breaking release uses a Conventional Commit subject with ! or a BREAKING CHANGE: footer.
Execution map
These are attached as GitHub sub-issues. Their blocked-by relationships are part of the issue graph:
Implementation is in progress in draft PR #289 and is assigned to @adrian-lorenzo. The subissues remain open as the acceptance map until the local, private deployment, hosted engine, GitHub App, remote preview, and retention checks are complete.
Codex and Claude sessions working on the implementation should read this epic, the relevant subissue, the repository instructions, and the current code. New product or security decisions should be recorded on the relevant issue instead of being hidden in code.
Context
Facility currently treats agent work as a sequence of short-lived runs. A run gets its own sandbox, produces a controlled delivery, and then ends. Conversations, previews, permissions, receipts, budgets, and agent definitions have separate lifecycle rules.
Today, a contributor who works across several runs has to reconstruct the environment and execution context. A contributor should be able to start from an issue, work for several days, run the whole application, ask another agent to continue, and inspect the result from a browser without rebuilding context on every turn.
Facility 0.12 will use a persistent workspace as the home of the work. The story, conversation, engine sessions, Git worktree, development services, and preview all refer to that workspace.
This is a breaking product change. We will build the replacement path, verify it, migrate the useful agent workflows, and remove the old run and receipt machinery before the release.
Product behavior
A user starts or opens a story from MCP or the Facility UI. Facility creates one durable workspace for it. The compute can sleep and can be replaced after a failure. The attached storage keeps the Git worktree, uncommitted changes, installed dependencies, local service data, and Claude Code or Codex session files.
The workspace can run the repository's development environment. Projects may use Docker, Docker Compose, setup scripts, seed data, and browser tests. Declared ports are available through an authenticated preview URL, so a person can test the running branch from another computer.
The same conversation is visible to every authorized project maintainer. A maintainer can send another message, choose another configured agent, or switch between the UI and an MCP client. Facility records which agent, engine, model, and manifest revision handled each turn.
Merge and archive change the story's status. They may put the compute to sleep. They do not delete the engine sessions, worktree, volume, conversation, or artifacts. Facility removes durable state only after an explicit delete action from an authorized user.
Agents as code
Every agent is configured in the repository under
.agents/. The file contains Markdown frontmatter and a prompt body. One parser and schema serve kickstart, the control service, MCP, the scheduler, and the UI.The initial kickstart crew contains:
architectbuilderpr-revieweraddress-reviewci-doctorsecurity-auditEach file declares its engine, model, optional reasoning effort, enabled state, and triggers. Triggers may be manual, MCP, UI, GitHub events, or a schedule. Teams can add another agent by adding another file that follows the same schema.
The server treats these names as data from the manifests. Model configuration lives in the repository file. A
codex-builder, for example, is an ordinary agent file whose engine is Codex and whose model is named in that file.The agent schema rejects permission, sandbox, tool allowlist, and similar fields.
Access model
All configured agents get the same access:
An architect, reviewer, scheduled audit, and interactive builder receive the same project capability. Facility has no read-only agent mode.
The remaining boundaries protect Facility users from each other and protect the control plane. Authentication, project membership, tenant and workspace isolation, secret handling, signed webhooks, preview authentication, and branch protection still apply. Facility issues short-lived GitHub credentials with the project's full maintainer capability for every agent and action.
Scheduled and event-driven work
Scheduled agents remain part of Facility. The scheduler reads the same
.agents/files as manual execution. A trigger posts a new message to a persistent story and dispatches a turn.PR review and CI repair reuse the story attached to the pull request. A recurring project task such as
security-auditgets a stable story, conversation, worktree, and set of engine sessions. Editing or disabling a schedule stops future turns and leaves its existing state intact.The dispatcher must deduplicate retries and concurrent scheduler replicas. Ordinary idempotency records replace receipt chains and the separate watchtower pipeline.
Recurring story identity uses project, manifest
name, and trigger identity. Renamingnamecreates a new recurring story. Removing or disabling the file leaves the old story available, and restoring the same name and trigger reconnects to it.MCP and UI
MCP is the main interface for coding agents and automation. Its public tools cover projects, configured agents, stories, conversation, environment status, preview access, suspension, archive and restore, and explicit workspace deletion.
The Facility UI stays in the product. It covers the same work for a person: project setup, the
.agents/catalog, model and trigger configuration, stories, attention, conversation, service status, logs, preview, archive and restore, and workspace deletion.Both interfaces call the same application services. MCP is hosted by the control service. Editing an agent in the UI changes the repository file through Git, which remains the source of configuration.
Storage and lifecycle rules
The following data survives compute suspension and replacement:
Idle time and merge may suspend compute. Archive is reversible. These events leave durable storage intact.
An explicit workspace deletion stops compute, revokes previews, and removes the durable volume and native session files. Story messages, turn metadata, pull request links, and lightweight artifact records remain as history. The UI and MCP response must state this boundary before the request is accepted. The operation is authorized, idempotent, and isolated to one project and workspace.
Work included in 0.12
The sub-issues attached to this epic cover:
.agents/format and kickstart outputScope excludes a hosted agent marketplace, per-agent permissions, a separate model or budget gateway, receipt verification, public previews, and a permanent compatibility mode. Monthly project budget enforcement remains part of the control plane. Preview access is limited to authenticated maintainers of the project.
Delivery approach
The replacement is being implemented as the Facility 0.12 path in draft PR #289. It uses one data model and does not maintain a permanent switch between old runs and story workspaces. Old services, tables, queues, and packages are removed only after their required behavior has a replacement test.
Provider, runtime, authentication, preview routing, multirepository behavior, agent-file writes, project secrets, and storage decisions are recorded under
apps/docs/docs/reference/decisions/with evidence from a working fixture. The fixture contains an application, an API, a database, seed data, a browser test, and more than one configured agent.Existing 0.11 operational history will not be migrated into the new workspace schema. Startup against a 0.11 database stops without modifying it. The release work documents backup, export, clean installation, and full 0.11 rollback.
Changes to authentication, project scoping, GitHub credentials, secrets, webhooks, or preview access require unit and deterministic integration tests. These tests must cover valid use, malformed input, expired and revoked credentials, replay, and cross-tenant denial. The default suite cannot require live credentials or network access.
Completion criteria
.agents/, with an explicit engine and model in every file.!or aBREAKING CHANGE:footer.Execution map
These are attached as GitHub sub-issues. Their blocked-by relationships are part of the issue graph:
.agents/contract and kickstart crew. It can start now.Current status
Implementation is in progress in draft PR #289 and is assigned to @adrian-lorenzo. The subissues remain open as the acceptance map until the local, private deployment, hosted engine, GitHub App, remote preview, and retention checks are complete.
Codex and Claude sessions working on the implementation should read this epic, the relevant subissue, the repository instructions, and the current code. New product or security decisions should be recorded on the relevant issue instead of being hidden in code.