Files
archie/docs/prds/extensions-center.md
T

11 KiB

Extensions centre

Status: Draft

Epic: archie-core-1786637490708-35-38424ead / GitHub #56 ("Replace Skills with a bundled Extensions centre").

Skills, Workflows, and Tools/MCP already exist as separate, working inventories with their own APIs (api_skills.go, api_workflows.go, config-driven MCP servers) and their own family-owned controller pattern (curator.Registry, health.Registry, image.Registry, workflow.Registry all already prove this shape). plugin.Plugin (internal/plugin/plugin.go) is already metadata-only, per docs/architecture/plugins-and-extensions.md. None of that is rebuilt here. What's missing, confirmed by grep, is: any config schema for enabling or disabling a capability, any "pending restart" state tracking, and any single inventory that reconciles configured/bundled/discovered/active state across families. This document decides those three things and the UI surface that presents them. It extends plugins-and-extensions.md rather than replacing it — that doc's decisions (metadata-only Plugin, typed capability families, no generic dispatch) are unchanged.

Out of scope: any remote or arbitrary-URL plugin installation path (the epic's own acceptance criteria forbid this, and plugin.LoadDir (plugin.go) already only reads ~/.config/archie/plugins/*.go — this document does not add a fetch-by-URL variant to it).

Problem

internal/config/config.go's MCPServer and ToolsConfig structs have no enabled field (confirmed by the investigation grep). api_config.go's UpdateConfig/handleConfigUpdate seam persists changes but has no state distinguishing "saved, takes effect now" from "saved, needs restart" — the only existing reload path (ReloadChannel, server.go) is channel-specific and explicitly does not cover plugins or MCP servers. server.go already wires five separate optional inventories (Workflows, Skills, Curators, Channels, Captures/Mappings/Bindings) as independent fields with no unifying type — an operator has no single place to see "what's available, what's enabled, what's actually running, and what's degraded" across all of them. ui/src/ has settings/, skills/, and workflows/ directories already; there is no ui/src/extensions/.

Design

Unified inventory type

package extensions // internal/domain/extensions — new, app-level aggregator

type State string

const (
    StateAvailable      State = "available"       // bundled, not configured
    StateEnabled        State = "enabled"          // configured on, not yet live
    StateActive         State = "active"           // configured on and running
    StateDegraded       State = "degraded"         // active but unhealthy
    StateSkipped        State = "skipped"          // optional, disabled by config
    StatePendingRestart State = "pending_restart"  // config changed, not yet live
)

type Entry struct {
    Family      string // "skill" | "workflow" | "tool" | "plugin" | "integration"
    Name        string
    Core        bool   // non-disableable
    State       State
    Health      string // reuses whatever the family's own registry already reports
}

type Inventory interface {
    List(ctx context.Context) ([]Entry, error)
}

Decision. extensions.Inventory is a read-only aggregator, not a new domain that owns state. It queries each family's existing registry (curator.Registry, health.Registry, workflow.Registry, the MCP client set, plugin.LoadDir's result) for live state, and compares that against the config-desired state (below) to compute StatePendingRestart — the diff is computed on read, not persisted, so there is no new durable state to keep consistent with the registries themselves. This follows migration-decisions.md's rule that cross-cutting aggregation composes existing domain-owned contracts rather than duplicating their state.

Call site. New package internal/domain/extensions/inventory.go. Composed in internal/app/archied (wherever server.go's other optional fields — Workflows, Skills, Curators — are wired) since it needs references to every family's registry, which only application-layer composition has.

Config-backed enablement

Decision. Add enabled bool (default true for pre-existing configured entries, so no upgrade silently disables anything already configured) to each family's config element: MCPServer.Enabled, and equivalent fields on whatever config types back skills/workflows/plugins if they don't already have an on/off switch. Core capabilities (identity, workflow engine, State Store connectivity — named in organisation.md's cross-cutting packages) have no enabled field at all; a config value can't be added to something that doesn't expose the toggle, which is the "non-disableable" property enforced structurally rather than by a runtime check that could be bypassed.

Call site. internal/config/config.go — add the field per family struct, not one generic map[string]bool (typed fields keep docsgen/contracts.json generation working, per tools/docsgen's "treat flags as executable truth" rule — a generic map has no type to generate from). config.example.toml documents each new field with its default.

Reuse check. The config Holder overlay system (internal/infrastructure/configuration) already handles safe saves; this adds fields to existing structs, it does not add a second config-write path.

Pending-restart and reconciliation

Decision. No new "pending restart" flag is persisted. Inventory.List computes StatePendingRestart by comparing the config's Enabled value against whether the family's registry reports that entry as live — if they disagree, the entry is pending restart. This is simpler than tracking a flag through a save-then-restart cycle and can never go stale, because it's recomputed on every read.

Call site. internal/domain/extensions/inventory.go's comparison logic.

API and UI surface

Decision. New api_extensions.go alongside the existing api_skills.go /api_workflows.go pattern, exposing Inventory.List and a save endpoint that writes through the existing UpdateConfig seam (api_config.go) — this document does not add a second config-write endpoint. New ui/src/extensions/ (colocated .js/.css per CLAUDE.md's frontend rule) as an index/dashboard that links to, not replaces, the existing ui/src/skills/ and ui/src/workflows/ detail views — Extensions centre is where an operator sees everything and toggles enablement; the family-specific pages remain where they inspect a family's own detail.

Call site. internal/webui/api_extensions.go (new, follows api_skills.go's shape), ui/src/extensions/ (new).

Call site inventory

concern file change
Plugin metadata type internal/plugin/plugin.go none — already handles this
Family controllers (curator/health/image/workflow registries) internal/domain/curator/registry.go, internal/domain/health/health.go, etc. none — pattern already proven, reused not rewritten
Unified inventory internal/domain/extensions/inventory.go new
Composition wiring internal/app/archied/server.go (near existing optional fields) new
Config enablement fields internal/config/config.go new fields per family
Config docs config.example.toml new field documentation
API surface internal/webui/api_extensions.go new
Existing skills/workflows APIs internal/webui/api_skills.go, api_workflows.go none — linked from, not replaced
Config save path internal/webui/api_config.go (UpdateConfig) reused, not duplicated
UI ui/src/extensions/ new
Existing UI detail views ui/src/skills/, ui/src/workflows/ none — linked from Extensions centre

Execution: multi-agent team breakdown

sub-feature issue implementer scope suggested council lenses why
Unified inventory type + composition file as child of #56 internal/domain/extensions/inventory.go, wiring in server.go lens-boundary, lens-deletionist boundary: aggregator must not duplicate family-owned state; deletionist: must not become a new domain that shadows existing registries
Config enablement fields file as child of #56 config.go per-family Enabled fields, config.example.toml lens-contract config field is a wire contract other tooling (docsgen) generates from
API + UI surface file as child of #56 api_extensions.go, ui/src/extensions/ lens-maintainer new user-facing state machine (available/enabled/active/degraded/skipped/pending-restart) must be legible to an operator with no prior context
  • #56 itself has no filed children yet — file the three rows above as child issues linking to this doc's matching ## heading.
  • Each issue's acceptance criteria should restate this doc's per-family Enabled default (true for existing config, no field at all for core capabilities) so "non-disableable core" isn't re-litigated per bead.
  • Add the suggested lenses to each issue.