Current State
This document describes what Metis can do today. It is a capability snapshot, not a history of how the platform got here and not a blueprint for where it is going. When capabilities change, this document is updated; when phases of work are completed, the relevant operational documentation is updated on its own cycle.
The description here is deliberately organized by capability rather than by implementation history, and it is deliberately paired with an explicit list of what Metis does not do yet — because knowing where the boundary is matters as much as knowing what is inside it.
What Metis Is Capable of Today
Identity and Access
Metis runs as a hosted team platform. Any member of our GitHub organization can log in through GitHub OAuth, and organization membership auto-admits them to the platform. Accounts are created on first successful login. A bootstrap-admin mechanism seeds the first administrator from a configured GitHub login; subsequent administrators are promoted by existing administrators, with a guardrail that prevents the last administrator from self-demoting.
Sessions are stateful, stored in the platform database, and anchored by an opaque cookie. Sessions can be revoked immediately by deleting the database row. Users can be deactivated by administrators; deactivated users lose access immediately but their owned data is retained and labeled appropriately until it is transferred to another user.
Administrators can promote users, demote other administrators, deactivate users, reactivate them, transfer ownership of a deactivated user’s resources to a living user, and inspect the audit log. Every ownership and visibility change writes an audit entry.
Ownership, Visibility, and Auditability
Every significant resource in the platform — codebases, conversations, workflows, commands, scripts, skills, MCP configurations, workflow runs, isolation environments — has an explicit owner and a visibility stance. The default visibility is team: any member of the organization can see the resource. Conversations can be flipped to private by their owner, in which case only the owner (and, by explicit override, an administrator) can see them.
All reads pass through a shared visibility filter that enforces “owner or team-visible” on every query. All writes check ownership or administrator role before proceeding. Flipping a conversation between private and team visibility is a deliberate action with a confirmation step when private content is about to be made visible; administrator overrides of another user’s resources are logged.
The audit log captures ownership transfers, visibility flips, administrative promotions and demotions, and administrator overrides. It is visible to administrators through a web UI.
Collaborative Workflows, Commands, Scripts, Skills, and MCP Configurations
Workflows, commands, scripts, skills, and MCP configurations are all first-class, database-backed, version-history-tracked, team-shared resources. Each has an owner; each is visible to the team by default; each can be created, read, updated, and deleted through the web UI; each carries a version history so that previous versions can be inspected and restored.
A discovery layer merges three sources at runtime: bundled defaults embedded in the platform image, platform-level resources stored in the database, and project-level resources in the target repository’s .metis/ directory. Precedence is project, then platform, then bundled. The worker materializes the merged set into its filesystem before running a workflow, so that every agent invocation sees a consistent set of resources regardless of where each piece originated.
The bundled defaults include a curated set of workflows, commands, skills, and an MCP configuration — seeded into the database at first deployment and refreshed on subsequent deployments when the bundled content changes. Platform administrators can add, remove, or customize these resources through the authoring UIs.
Bring-Your-Own-Key Credentials
Every user can supply personal Anthropic and OpenAI keys through the settings UI. Keys are stored in the platform’s configured secret store — not in the application database — and the database holds only a pointer. When a workflow runs, the platform resolves the key for each required provider by checking the user’s personal keys first, then falling back to an enterprise key configured by an administrator. If neither is configured, the run fails with a clear error directing the user to settings.
Administrators manage the enterprise fallback through a separate administrator-only surface. Key rotation and deletion are supported; key values are never echoed back to the user after they are saved.
GitHub-Integrated Codebase Registration
Codebases are registered through a GitHub App installed at the organization level. Administrators install the app and grant it access to specific repositories; platform users then see a repo-picker populated with the repositories the app can access. Clones are performed server-side using installation tokens; the previous local-path and URL-based registration flows have been retired.
A codebase carries metadata about its GitHub origin, a connection state (for example, pending_github_access when the app has not yet been granted access to the repo), and per-codebase environment variables that are injected into workflow runs.
Queue-Backed Workflow Execution
Workflow runs are dispatched through a queue-based execution split. The web-and-API process accepts the request, records a durable execution snapshot, and enqueues a run keyed by its identifier. A separate worker process claims the run, creates a hidden worker conversation, resolves the isolation environment, materializes the full merged resource set into the worker’s filesystem, supervises the one-shot worker child that executes the workflow, publishes progress events through the platform event bus, and writes artifacts to the platform object store.
Workflows run in isolated git worktrees by default, so that a failed or runaway run does not damage the live checkout. The isolation environment is tracked in the database, is owned by the same user who owns the run, and carries a heartbeat lock that is in final validation as part of ongoing work to prevent concurrent runs from competing for the same worktree. On completion, artifacts are persisted and served through a backward-compatible artifact API.
Direct chat and orchestrator AI interactions continue to run in-process; only the workflow execution path is queue-backed today.
Observability Through the Event Stream
Every workflow step emits structured events, which are persisted to the database, published to the event bus, and streamed to connected web clients through server-sent events. The UI shows run progress in real time. Audit-relevant mutations write audit log rows.
Structured logs use a consistent event-naming convention and a single Pino-backed logger factory, making it possible to follow a run from dispatch through completion by correlating event emissions across the web process and the worker process.
Workflow Authoring
Workflows are authored either as YAML in a repository’s .metis/workflows/ directory or through the platform workflow builder UI, which saves to the database. A validation endpoint lets authors verify a definition before saving. Bundled defaults can be exported for reference; user-defined workflows can be created, updated, and deleted through the API. Deleting a bundled default is not permitted; the platform serves the bundled version when no database or project-level override exists.
Commands have an authoring UI of their own. Scripts and MCP configurations are authored through dedicated admin surfaces with version history. Skills are currently authored by tarball upload and download; a proper in-browser authoring UI for skills is acknowledged as future work.
Ownership Locks
Conversations and isolation environments have heartbeat-based active-use locks. A conversation lock blocks non-owners from sending messages, approving, or rejecting while an AI interaction is active, but allows view and stream access to team-visible conversations. An isolation-environment lock prevents a second workflow run from picking up a worktree that is currently in use. Both lock types use expiry-by-heartbeat rather than cleanup processes. The lock implementation is in final validation at the time of this writing and has not yet been merged into the working branch.
The Boundaries of Today’s Metis
The following capabilities are explicitly not present in today’s platform. They are listed here because the boundary matters — a capability that looks like it might work and does not is worse than a capability that is honestly absent.
- Intent capture as a first-class artifact. Conversations are the current place where intent lives. There is no typed brief object, no dedicated authoring surface for product intent, no approval gate on intent before downstream work begins.
- Requirements decomposition with a human approval gate. Plans exist in the repository as files in
docs/superpowers/plans/, and workflows can include approval nodes that block on human review, but there is no first-class requirements artifact, no collaborative editing surface for stakeholders, and no explicit gate between “requirements drafted” and “implementation begins.” - An indexed, queryable context graph across artifacts. Links between conversations, workflows, runs, PRs, and releases are implicit — you can derive them by walking the database — but they are not exposed as a navigable graph in the UI, not indexed for cross-project queries, and not surfaced to agents as a research substrate.
- Multi-agent critique as a first-class workflow primitive. A workflow can invoke different providers on different nodes, but a reusable “draft with agent A, critique with agent B, reconcile” pattern is not a bundled node type or a bundled workflow shape.
- A work queue with WIP limits. Workflow runs start when dispatched. There is no visual board, no WIP cap per project or per owner, and no cost-budget-driven sequencing.
- Webhook-driven intake. Bugs and feature requests arriving in GitHub Issues, Slack, or email do not automatically produce Metis briefs. Humans still translate external signals into Metis work manually. Dormant Slack and GitHub-webhook adapters remain in the tree but are not wired into the hosted deployment.
- Reusable project patterns at the team level. Workflows can be bundled or team-shared, but there is no concept of a “blueprint” — a parameterized, inheritable template a team instantiates for a new project.
- A visual workflow editor. Workflows are authored in YAML or through a form-driven UI. A DAG canvas with drag-and-drop node composition does not yet exist.
- Persistent worker pools, warm container caches, cross-run checkpoint resume, large-repo optimization. Workers are one-shot and ephemeral. Each run incurs the cost of a cold start and a fresh clone.
- Two-way integration with external work-tracking tools. We do not push status back to Linear, Jira, or equivalent systems, and we do not broadly ingest events from them.
- A trust-calibration model. Audit logs and workflow events exist, but the feedback loop that converts evidence of agent performance into progressive automation of gates is not implemented.
- Cross-project analytics and dashboards. Raw data exists per run; rolled-up cross-project analytics do not.
- First-class governance artifacts produced by the platform. ADRs, change records, compliance reports, and retrospectives are produced outside Metis, if at all, and linked back manually if they are linked at all.
- A CLI surface backed by the shared execution model. The original single-user CLI has been retired; a rebuilt CLI that issues dispatches against the same queue/worker/event-bus model as the web UI is acknowledged future work.
Deployment Shape
Metis is designed around a serverless-first cloud topology with an explicit local-development mode that emulates the hosted infrastructure through container-based stand-ins. The topology is deliberately abstracted behind a small set of interface contracts so that the same code runs against the cloud services in production and against local emulators in development.
The core building blocks are: a stateless web-and-API service that serves both the UI and the REST surface and scales to zero when idle; a worker execution surface that runs individual workflow jobs in isolated, one-shot containers; a managed Postgres database that is the platform’s source of truth; a private object storage layer for artifacts, skills, and ephemeral uploads; a secret store that holds every API key, credential, and private key; a dispatch queue that brokers runs from the web service to the worker; and an event bus that fans workflow events out to subscribed web instances for real-time streaming.
Four interface abstractions — a secret store, a job dispatcher, an object store, and an event bus — are selected once at process start based on the environment. In production, those interfaces resolve to the cloud’s native services. In development, they resolve to container-based emulators that run under Docker Compose alongside a local Postgres instance. A developer can bring up the full platform locally, register a dev GitHub OAuth application, and exercise every code path without requiring a cloud account.
Three environments are named in the platform’s operating model: local development, a hosted staging environment, and a hosted production environment. Staging is the current deployment target; production bring-up is deferred until staging has been shaken out.
Operational Stance
The platform’s operational stance is to keep the local development loop trustworthy and the staging environment close in shape to production. Schema migrations are numbered and idempotent, applied automatically on boot, so that “drop the database and re-create it” is always a supported operation and so that a new contributor can stand up the stack without manual database work. Staging is deployed continuously from the working branch; production is a deliberate manual promotion.
The documentation posture is that the platform’s own docs — this document set and the operational docs elsewhere in the repository — are a first-class deliverable. A platform that teaches people how to use it has a different character from one that assumes the intended audience will figure it out.
This document will fall out of date the moment a new capability lands or a boundary moves. When that happens, the appropriate action is to update this file; it is not appropriate to leave a stale capability claim standing because the new work was “minor.” The value of a current-state document is that it is current.