# archie-core v2 Architecture -- Design Document **Author:** Archie **Date:** 2026-07-21 (implementation status updated 2026-07-22) **Status:** Final (substantially implemented -- remaining aspirational items are pluggable storage backends and Layer 2 daemon plugin loader) --- ## 0. Implementation status (as of 2026-07-22, updated 2026-07-22) This document describes a target end state. The table below is the ground truth; read it before treating any section as already built. | Area | Status | What actually exists today (post-e4d11b1) | |---|---|---| | Daemon/agent binary split | **Implemented** | `cmd/archied` and `cmd/archie-agent` both exist. `archie-agent` is a 189-line NATS-connected per-task worker that subscribes to task subjects, runs the full multi-stage workflow, and reports results. Workflow routing and sequencing (`workflow.Route`, `workflow.Run`) now run inside the agent, not the daemon. Three agent modes: `inprocess`, `subprocess`, `nats`. | | Sandbox / "daemon never runs untrusted code" | **Partial** | Default mode is still `inprocess` for development. Docker sandbox mode (`agent.mode = "nats"` + `containers.enabled = true`) runs each task in an ephemeral Docker container with workspace bind-mounted at `/workspace`. `internal/container/pool.go` manages full lifecycle: pull, create, start, release, orphan recovery. Daemon dispatch and container lifecycle both enforce `max_concurrency`; same-repo tasks remain serialized. | | NATS / JetStream messaging | **Implemented** | `internal/nats/client.go`: JetStream connect, stream creation (WorkQueue retention, file storage), pull consumer (durable, ack-wait 5min, max-deliver 3, dedup by Msg-Id), `PublishTask`, `Fetch`, `NewReplyInbox`, and optional token authentication. Subject hierarchy lives in `internal/nats/subjects.go`; `internal/agentexec/nats.go` implements request/reply agent execution. | | Docker container sandbox | **Implemented** | `internal/container/pool.go` (210 lines): Docker API client, image pull (always/missing/never), container create with workspace bind mount, start, release (stop+remove), orphan recovery on daemon restart. `Dockerfile` at repo root builds archie-agent fat image. `[containers]` config block: enabled, image, max_concurrency, max_uptime, pull_policy. `agent.mode = "nats"` required when containers enabled. | | `/data/` volume, `task.json` | **Partial** | `container.WriteTaskJSON()` writes task payload to the worktree before container acquire. The container pool bind-mounts the isolated task worktree at `/data/worktree`; configured repos also receive a persistent `/data/repo` Docker volume. Task payload travels over NATS as the primary channel; `/data/task.json` is a boot-time brief for the container. | | `[containers]` config block | **Implemented** | `ContainerConfig` struct in config.go: enabled, image, max_concurrency, max_uptime, pull_policy. Validated on load. | | Yaegi extensibility (gates, custom stages, skill scripts) | **Implemented** | Three surfaces: `.archie/gate.go`, `.archie/stages/*.go`, skill scripts via `run_go_script` tool. All in-process via Yaegi with generated symbol tables and panic recovery. Full detail in `docs/prds/yaegi-plugin-system.md`. | | Layer 1: skill-bundled plugins | **Implemented** | `skill.DiscoverPlugins()` scans `.agents/skills//plugins/*.go`. `skill.Plugin.Run()` executes them via Yaegi. `skillbuild.BuildWorkflow()` constructs `workflow.Workflow` from plugin-defined stages. `TaskContext.SkillPlugins` makes them available during stage execution. `skillbuild.BuildRegistry()` replaces the hardcoded `workflow.Registry` with catalog-driven construction -- skills define workflows, plugins define stages. | | Layer 2: core daemon plugins | **Partial** | `internal/plugin/plugin.go`: `Plugin` interface (`Name()`, `Version()`), `Registry` type, `LoadDir()` using Yaegi to interpret `.go` files. No `~/.config/archie/plugins/` loader wired into `cmd/archied/main.go` yet -- the interface and registry exist but are not connected to the daemon's startup. | | Skills (agentskills.io spec) | **Implemented** | `internal/skill/skill.go`: parses SKILL.md YAML frontmatter, discovers skills from `.agents/skills/*/SKILL.md`, extracts body. Skills follow `archie-wf-*` naming convention. Progressive disclosure: `Catalog()` (Tier 1 -- frontmatter-only scan, ~100 tokens per entry), `LoadBody()` (Tier 2 -- full body on activation), `Discover()` (Tier 3 -- full parse with plugins). `metadata.archie.workflow` declares skill→workflow affinity. `skill.SkillForWorkflow()` is catalog-driven, no hardcoded maps. `skillbuild.BuildRegistry()` constructs the daemon's workflow registry from the catalog. | | Worktree/repo management | **Implemented** | Each issue keeps an isolated worktree. Repos with `persistent_storage = true` use a per-repo bare Git object cache to avoid repeated full network clones; caches and Archie-owned repo volumes expire via `containers.volume_ttl`. | | Config schema | **Closer to sec.4** | `[agent]` block: mode (inprocess/subprocess/nats) + command + env. `[nats]` block: url + token_env. `[containers]` block: enabled, image, max_concurrency, max_uptime, volume_ttl, pull_policy. Per-repo `persistent_storage` is supported as a boolean Docker-volume/Git-cache opt-in. | **Net read post-1dca419:** Phases 1, 2, and 3 are substantially implemented. NATS, Docker sandbox, skill parsing, skill-bundled plugins (Layer 1), skill progressive disclosure, and catalog-driven workflow construction (`skillbuild.BuildRegistry()`) all landed. The remaining aspirational work is Layer 2 daemon plugin loader (interface exists, not wired), pluggable storage backends, and per-worktree dynamic registry augmentation. --- ## 1. Binary split ### archied (daemon) The resident orchestrator. Owns: - **Task discovery** -- polls configured forges for issues labelled `archie` (or configured label) - **NATS publishing** -- publishes discovered tasks to JetStream subjects - **Container lifecycle** -- spawns Docker containers, kills them after grace period, cleans up volumes - **Message gatekeeping** -- reads agent responses from NATS, reviews them, forwards to human channels - **Core plugin loading** -- loads Yaegi `.go` plugins from `~/.config/archie/plugins/` at startup - **Web dashboard** -- SSE observability endpoint - **Human communication** -- issue comments, labels, PR management, notify webhook The daemon never runs untrusted code. Agent containers are the sandbox boundary. > **Target state, not current state.** Today, default `[agent] mode = "inprocess"` runs the agent loop (and therefore > all LLM-directed tool calls) directly inside `archied`. `subprocess` mode exists (`internal/agentexec/subprocess.go`) > but its own code comment says: _"This is not an OS security boundary: a same-UID subprocess may still access > daemon-readable host resources."_ This claim becomes true only once the Docker sandbox (sec.4, Phase 2) lands. ### archie-agent (ephemeral container) Spawned per task. Lives in a Docker container. Receives its brief via `/data/task.json` (volume-mounted). Owns: - **Workflow execution** -- runs the routed workflow stages (implement, tdd, feasibility, bootstrap) - **LLM orchestration** -- via `ai-sdk/agentloop`, the agent drives LLM calls - **Bundled plugin loading** -- loads Yaegi `.go` plugins from the skill's `plugins/` directory and the `/data/plugins/` volume - **Skill loading** -- reads `.agents/skills/archie-wf-*` from the worktree, follows the agentskills.io progressive disclosure model - **NATS reporting** -- publishes results to `archie.agent..response`, system messages to `archie.agent..system` Lifecycle: spawn -> load task -> run workflow -> report -> wait for follow-ups (grace period) -> killed by daemon. > **Target state, not current state.** `cmd/archie-agent/main.go` today is 28 lines: read one JSON `Invocation` from > stdin, run one stage via `agentexec.ServeOne`, write one `Response` to stdout, exit. It is a single-stage subprocess > worker invoked by `archied`'s `SubprocessRunner`, not a persistent per-task container process. Workflow routing and > multi-stage sequencing (`workflow.Route`, `workflow.Run`) run entirely inside `archied` > (`internal/daemon/daemon.go:process()`), not inside archie-agent. There is no `/data/task.json`, no bundled-plugin > loading, no `.agents/skills/archie-wf-*` discovery, and no NATS reporting -- see sec.0, sec.2, sec.3, sec.5. The > existing `agentexec.Runner` interface (`InProcessRunner`/`SubprocessRunner`) is, however, deliberately shaped so a > future container-backed runner can be a drop-in swap without changing workflow orchestration. --- ## 2. NATS subject hierarchy > **Status: aspirational, zero code.** No NATS/JetStream dependency exists anywhere in `go.mod` or the codebase. Today, > task discovery is GitHub-poll-driven (`daemon.Run()` ticks on `PollInterval`, calls `pollIssues()`), distribution is a > SQLite `tasks` table used as a FIFO queue (`store.ClaimNext` atomically claims the oldest `queued` row), and > results/status flow through an in-process `internal/events.Bus` (Go channels, multi-subscriber fan-out, > drop-on-overflow) that already feeds both a SQLite `events` table and the SSE dashboard. `events.Bus` has roughly the > right shape to become the NATS publish path -- same `Event` schema, swap the transport -- which meaningfully de-risks > this phase, but it is currently single-process only with no network transport. ### Task distribution ```events archie.task.bug -- TDD workflow tasks archie.task.feature -- Feasibility workflow tasks archie.task.default -- Implement workflow tasks archie.task.bootstrap -- Bootstrap diagnostic tasks ``` Daemon publishes to the appropriate subject based on label routing. Agents subscribe to subjects they're configured to handle. ### Agent communication (per-task) ```events archie.agent..response -- Agent output: summaries, PR bodies, results. Daemon reviews before human delivery. archie.agent..system -- Internal comms: log dumps, data requests, health, PII warnings. Never forwarded unprompted. archie.agent..request -- Optional: agent requests additional data from the daemon. ``` The daemon gatekeeps the response channel -- no agent output reaches a human without daemon review. ### JetStream durability Tasks are published with JetStream persistence. On agent container failure, NATS redelivers. The daemon doesn't need retry logic -- NATS handles it. --- ## 3. Persistent volume > **Status: partially implemented.** `task.json`, `/data/worktree`, optional per-repo `/data/repo` Docker volumes, > ecosystem cache volumes, and TTL cleanup exist. Task worktrees remain isolated by issue, while configured repos use a > per-repo bare Git object cache to seed clones without repeating full network transfers. `session.jsonl`, > `memory.jsonl`, and staged plugin volumes remain unimplemented. ### /data/ layout ```tree /data/ |---- task.json # Full task payload (owner, repo, issue, title, body, labels, workflow) |---- session.jsonl # Agent session transcript (appended per stage) |---- memory.jsonl # Optional: cross-session memory (persisted per project) |---- plugins/ # Bundled plugins from the skill (daemon-staged, overrides worktree) |---- worktree/ # Read-only mount of the cloned repo (managed by daemon) ``` ### task.json ```json { "id": 42, "owner": "sam", "repo": "example-service", "issue_number": 170, "title": "Add /copy command for messages and session transcripts", "body": "...", "labels": ["enhancement", "archie"], "workflow": "implement", "branch": "archie/issue-170", "plan": "", "config": { "base_branch": "main", "gate": [ ["gofumpt", "-w", "."], ["go", "vet", "./..."], ["go", "test", "-race", "./..."] ], "protect": ["_templ.go"], "ecosystem": "go", "test_glob": "*_test.go" }, "nats": { "url": "nats://archie-core:4222", "response_subject": "archie.agent.42.response", "system_subject": "archie.agent.42.system", "request_subject": "archie.agent.42.request" } } ``` The daemon writes `task.json` to the volume before the container starts. The agent reads it on boot. ### Volume lifecycle - Created on task start (persistent per-repo if configured) - Kept until terminal outcome (`pr_open`, `merged`, `rejected`, `closed_wont_do`) OR TTL expiry - Parked tasks keep their volume for inspection and requeue reuse - Cleanup is a daemon responsibility --- ## 4. Container management > **Status: implemented with a flatter schema than the sketch below.** `[containers]` configures the image, > concurrency, uptime, pull policy, and persistent-storage TTL. `Repo.PersistentStorage` opts a repository into the > per-repo Docker volume and Git object cache. The backend abstraction exists in `internal/storage`; additional storage > types and structured per-backend configuration remain future work. ### Daemon config ```toml # Container lifecycle [containers] max_concurrency = 4 # max simultaneous agent containers max_uptime = "30m" # grace period after task completion before kill volume_ttl = "72h" # max volume age before cleanup (overrides terminal wait) # Image strategy [containers.image] registry = "ghcr.io/sam/archie-agent:latest" # primary: pull from registry registry_pull = true # allow pulls dockerfile = "./Dockerfile.agent" # fallback: build locally dockerfile_build = true # allow builds # Persistent storage [containers.persistent_storage] type = "docker" # docker (volume), bind, s3, sftp, nfs path = "archie-data" # volume name or mount path ``` ### Per-repo persistent storage override ```toml [[repos]] owner = "sam" name = "example-service" persistent_storage = { type = "bind", path = "./archie-core-data/projects/example-service" } ``` When configured, each task for this repo mounts the same bind path. Memory persists across sessions. The agent writes to `MEMORY.md` in this directory. ### Agent image A fat Docker image containing: - archie-agent binary - NATS client library - LLM provider SDKs (ai-sdk runtime) - Base tools: git, gh, go, golangci-lint, gofumpt, node, python, ruff, pytest, etc. - esbuild (for TypeScript plugin transpilation) - Yaegi interpreter (bundled in the binary) Pre-built and published to a registry. The daemon pulls on startup. Users can provide their own image via config. --- ## 5. Extensibility layers > **Reconciliation note.** This section describes a two-layer plugin architecture (skill-bundled plugins loaded > per-task, core daemon plugins loaded at startup) that does not exist in code. What _does_ exist -- and is implemented, > tested, and already in production -- is described in the sibling PRD `docs/prds/yaegi-plugin-system.md`, whose three > phases (custom gate functions, custom workflow stages, skill scripts) are marked "implemented" and match disk state > exactly as of commit `d45f21d`. That implementation is narrower and shaped differently than what follows: > > - It has **no skill-bundling concept** -- `.archie/gate.go` and `.archie/stages/*.go` are repo-level, not shipped > inside a skill's `plugins/` directory; skill scripts (`.archie/skills//scripts/*.go`) are the closest analog > but none of the five current skills ship a `scripts/` directory yet. > - It has **no daemon-side core plugin registry** -- no `Plugin` interface, no `Register(daemon *Daemon)`, no > `~/.config/archie/plugins/` loader. Yaegi today only interprets small, narrowly-scoped `.go` files (gates, stages, > scripts) in-process inside `archied`, using generated symbol tables (`internal/gate/gateextract`, > `internal/workflow/wfextract`) rather than a general extension-registration interface. > - Custom stages are **auto-discovered and run in filename order**, not routed by name from `config.toml` -- the > workflow engine has no data-driven stage graph today, so the `[[workflows.stages]]` config sketch below does not > correspond to real config. > > Before implementation begins, decide: does Layer 1/Layer 2 as described below _replace_ the existing three Yaegi > surfaces, or does it _extend_ them (e.g., teach the existing loaders to also read from a skill's `plugins/` directory, > and add a genuinely new daemon-side `Plugin` interface as a separate, later addition)? The existing surfaces are > working code with real symbol-table generation and panic recovery -- treat them as the implementation substrate for > Layer 1, not as something to discard. ### Layer 1: Skills (`archie-wf-*`) > **Status: cosmetic only.** Five `SKILL.md` files exist today (`ecosystem-node`, `ecosystem-python`, `go-quality-gate`, > `security-audit`, `tdd-bugfix`) at `.archie/skills//SKILL.md` -- a single flat repo-relative location, no > worktree-vs-user-level split, no `archie-wf-*` naming. Each has a `metadata.archie` block with only `tools` and > `engine` keys (no `plugins`, no `budget_usd`). **No Go code parses SKILL.md frontmatter, discovers skills, or does > progressive disclosure** -- grepping for a skill loader, catalog, or frontmatter parser across the repo returns > nothing. The workflow `Mission` strings that drive agent behavior today are hand-written Go string literals in > `internal/workflow/{implement,tdd,feasibility}.go`, not content injected from SKILL.md. The stage names described in > the PRD's SKILL.md prose closely mirror the hardcoded Go stage names (one drift found: `tdd-bugfix/SKILL.md` says the > last stage is "deliver"; the code calls it `open-pr`) -- these read as retrofitted documentation of existing v1 > behavior wearing v2-flavored frontmatter, not a functioning specification the daemon consumes. Skills are Markdown documents following the [agentskills.io](https://agentskills.io/specification) specification with archie-specific extensions. #### Discovery ```tree .agents/skills/archie-wf-tdd/SKILL.md (worktree -- highest precedence) .agents/skills/archie-wf-implement/SKILL.md .agents/skills/archie-wf-feasibility/SKILL.md ~/.archie/skills/archie-wf-default/SKILL.md (user-level -- fallback) ``` The agent discovers skills at workflow start. The skill matching the task's workflow type is loaded first. If absent, falls back to `archie-wf-default`. If that's absent too, the agent works from AGENTS.md conventions and best practices. #### Extended agentskills.io format Skills follow the standard spec (`name`, `description`, `version`, `SKILL.md` body) with archie-specific metadata: ```yaml --- name: archie-wf-tdd description: > Test-driven bugfix workflow for archie-core. Reproduce the bug with failing tests, prove the repro, fix the code without touching tests. version: 1.0.0 metadata: archie: plugins: # bundled Yaegi plugins shipped with this skill - plugins/custom-gate.go # repo-specific gate logic - plugins/gosec-check.go # security scanner integration tools: [go, golangci-lint, gofumpt, task] engine: any budget_usd: 2.00 --- ``` #### Progressive disclosure Per the agentskills.io spec: 1. **Catalog** (~100 tokens): `name` + `description` loaded at workflow start 2. **Instructions** (<5000 tokens): Full `SKILL.md` body when the skill is activated 3. **Resources** (as needed): References, scripts, and bundled plugins loaded on demand #### Bundled plugins A skill's `plugins/` directory contains Yaegi `.go` files. These are loaded by the agent at workflow start alongside the skill instructions. The daemon copies them to `/data/plugins/` before the container starts. If `/data/plugins/` already has a plugin with the same name (from persistent project storage), the volume version wins. Conflicts are logged by the daemon. ### Layer 2: Core plugins > **Status: aspirational, zero code.** No `Plugin` interface, no plugin registry, no `~/.config/archie/plugins/` loader > exists anywhere in the repo (confirmed by grep for `Plugin`, plugin registry, and `Register(daemon` -- zero matches). > Yaegi is a real dependency (`traefik/yaegi v0.16.1`) and is genuinely wired up, but only for the three narrow surfaces > in sec.5's reconciliation note above, all interpreted in-process inside `archied` -- not for extending the daemon with > new forge/ticketing/storage/secrets/notify implementations as described below. Core plugins live at `~/.config/archie/plugins/` and extend the daemon itself: ```tree ~/.config/archie/plugins/ |---- forge-gitea.go # Gitea forge implementation |---- forge-gitlab.go # GitLab forge implementation |---- ticketing-jira.go # Jira ticketing integration |---- ticketing-linear.go # Linear ticketing integration |---- storage-s3.go # S3 persistent storage backend |---- vault-secrets.go # HashiCorp Vault integration |---- notify-servicenow.go # ServiceNow integration ``` #### Loading Loaded by the daemon at startup via Yaegi. Each plugin registers itself with the daemon's extension registry: ```go // Plugin interface (Go, interpreted via Yaegi) type Plugin interface { Name() string Version() string Register(daemon *Daemon) error } ``` The daemon discovers `.go` files, evaluates them, extracts the plugin symbol, and calls `Register()`. Failed plugins are logged and skipped -- the daemon starts with remaining plugins. #### What core plugins can do - **Forges** -- implement the `forge.Forge` interface. Register themselves as available forge types. - **Ticketing** -- implement a ticketing interface. Poll external systems, format issues into the standard `forge.Issue` struct. - **Storage backends** -- implement a storage interface. Provide volume population and cleanup. - **Secrets** -- implement a vault interface. Inject credentials into `/data/secrets/` before agent start. - **Notifications** -- implement a notify interface. Deliver PRDs, status updates beyond the built-in webhook. --- ## 6. Task lifecycle (v2) > **Status: implemented.** NATS JetStream is now the task distribution path (`internal/nats/client.go`, `internal/daemon/daemon.go:drainNATS()`). Docker containers spawn per task (`internal/container/pool.go`). The flow below matches the running code post-e4d11b1. ``` Discover -> Publish to JetStream -> Agent consumes -> running(workflow:stage) v pr_open -> merged | rejected v waiting_human -> (approved) -> requeue v parked ``` ### Detailed flow 1. **Discover** -- daemon polls forges for labelled/assigned issues 2. **Publish** -- daemon publishes task to `archie.task.` JetStream subject 3. **Spawn** -- daemon creates task volume, writes `task.json`, stages bundled plugins 4. **Start container** -- `docker run` with volume mounts, network (NATS), resource limits 5. **Agent boots** -- reads `task.json` from `/data/`, connects to NATS, discovers skills, loads bundled plugins 6. **Run workflow** -- agent executes routed workflow stages. Reports progress to system channel. Result to response channel. 7. **Daemon reviews** -- reads agent response. Forwards to human channels (issue comment, label update, PR). System messages stay internal. 8. **Grace period** -- agent stays alive for `max_uptime`. Handles follow-ups (gate re-runs, human replies forwarded by daemon). 9. **Kill** -- daemon kills container. Volume cleaned up on terminal outcome or TTL expiry. --- ## 7. Agent -> daemon -> human flow ```flow ,---------, response ,---------, reviewed ,----------, | Agent |------------ -> | Daemon |------------ -> | Human | | | system | | queried | channels | | |------------ -> | |<-------------| | |------------ |------------ |------------- | |---- Issue comments (parked, PR, waiting) |---- Label updates (archie:queued -> archie:working -> archie:pr) |---- Notify webhook (feasibility PRD delivered) |---- SSE dashboard (real-time observability) ``` The agent writes whatever it wants to `response`. The daemon reviews it. No agent output reaches a human unprompted. The `system` channel is purely internal -- the daemon reads it for observability and debugging, never forwards it. --- ## 8. Implementation phases > Updated 2026-07-24 against actual repo state (see sec.0). Items marked **done** exist in the current tree; nothing else in > this document is implemented beyond them. Phase ordering below is unchanged from the original sketch except Phase 3, > which now builds on top of existing Yaegi work instead of assuming a blank slate. ### Phase 1: Binary split + NATS - ~~Split `archied` into daemon binary~~ -- **done**, `cmd/archied` exists - ~~Create `archie-agent` binary~~ -- **done, but partial**: `cmd/archie-agent` exists and executes one workflow _stage_ per invocation over a versioned stdin/stdout JSON protocol (`internal/agentexec`, protocol v1). Still needed: promote it from a single-stage subprocess worker to the PRD's per-task process, and move workflow routing/sequencing (`workflow.Route`/`workflow.Run`) out of `archied` and into it. - ~~Add NATS to both (JetStream for task queue, request-reply for comms)~~ -- **done**. `[nats]` is optional, supports anonymous local mode and token authentication via `token_env`, and leaves `internal/events.Bus` as the local observability fan-out. - ~~Daemon publishes, agent consumes, results return via NATS~~ -- **done**. Task discovery uses JetStream work-queue subjects; autonomous stages use JetStream requests plus core NATS reply inboxes. - Current single-process mode preserved for development (`--local` flag) -- effectively already true: `inprocess` `[agent] mode` is the _default_, not an opt-in fallback, so this constraint is satisfied but should be revisited once subprocess/container modes are the default. ### Phase 2: Docker sandbox - Docker agent image (fat, with tools) -- not started - Daemon container lifecycle: spawn, volume create, env inject, kill -- not started - ~~Persistent volumes with TTL~~ -- **done**: configured repos receive a persistent Docker volume plus a per-repo Git object cache; both are automatically reaped using `containers.volume_ttl`. - ~~`max_concurrency` enforcement~~ -- **done**: SQLite and NATS drains dispatch different repositories concurrently up to `[containers].max_concurrency`; same-repo tasks remain serialized by default. - Grace period `max_uptime` -- not started - **Groundwork already in place:** `agentexec.Runner` (`InProcessRunner`/`SubprocessRunner`) is an interface designed, per its own doc comments, to be swapped for a container-backed runner without touching workflow orchestration -- implement `ContainerRunner` against this interface rather than redesigning the execution boundary. ### Phase 3: Skills + bundled plugins - agentskills.io spec implementation (progressive disclosure) -- not started; current SKILL.md files are unparsed documentation (see sec.5) - `archie-wf-*` skill discovery from worktree and user paths -- not started; current skills live at a single flat `.archie/skills/` path with different naming - Bundled plugin loading via Yaegi from skill's `plugins/` directory -- not started, but **has a working substrate to extend**: `internal/gate/gateeval`, `internal/workflow/wfeval`, and `internal/skillscript` already interpret `.go` files via Yaegi with generated symbol tables and panic recovery (see `docs/prds/yaegi-plugin-system.md`, Phases 1--3, done). This phase should teach those loaders to also discover files from a skill's `plugins/` directory, not build a second Yaegi integration from scratch. - Volume-staged plugins with conflict resolution -- not started, and depends on Phase 2's volume work existing first ### Phase 4: Core plugins - Yaegi plugin loader for `~/.config/archie/plugins/` -- not started (no `Plugin` interface, no registry, no loader exist today) - Plugin registry in daemon -- not started - Gitea forge as first core plugin (proof of concept) -- not started (current `internal/forge` only implements GitHub REST polling) - Linear ticketing as second core plugin -- not started ### Phase 5: Pluggable storage - Docker volume backend (built-in) -- not started - Bind mount backend (built-in) -- not started - S3, SFTP, NFS backends as core plugins -- not started --- ## 9. Open questions 1. **Agent image versioning:** Use tagged versions (`:v1.2.3`) with a "never repoint tags" policy. `:latest` is for dev only, not the config default. No digest complexity needed -- archie-core is self-hosted, not a public registry. 2. **NATS auth:** Anonymous for single-node deployments (daemon + NATS + agents on same host). Credentials required for multi-node/cluster. Add an optional `[nats]` config block (default: anonymous, validated only when present). 3. **Worktree ownership:** ~~Answered by current implementation.~~ Fresh `git clone` per task attempt, no shared cache. This is fine for v2. Revisit if concurrent agents on the same repo become a bottleneck. 4. **Grace period interaction:** Reset `max_uptime` on human reply -- the agent just did useful work. But cap total lifetime with `max_total_uptime` (e.g. 4 hours) to prevent infinite hanging. `max_uptime` = grace after inactivity, `max_total_uptime` = absolute kill switch. 5. **Concurrent agents on the same repo:** ~~Resolved.~~ Serialized by default (dispatcher chains tasks per `owner/repo`). `[[repos]]` now supports `allow_concurrent = true` (`config.Repo.AllowConcurrent`) to opt a repo out of that serialization; the global `[containers].max_concurrency` slot limit still applies. Worktrees are already keyed per issue number (`worktree.Manager.Dir`), so opted-in repos don't collide on disk. 6. **Plugin architecture reconciliation:** Extend the existing Yaegi surfaces (`internal/gate/gateeval`, `internal/workflow/wfeval`, `internal/skillscript`) rather than building a parallel `Plugin.Register(daemon)` interface. Core plugins follow the same pattern: `Eval()` a `.go` file, extract known symbols. Settled before Phase 3/4. 7. **Skill loading scope:** "Parse frontmatter, inject body into system prompt" is sufficient for v2. The gap is that nothing reads SKILL.md today -- closing that gap is the value. Full progressive disclosure (catalog -> activate -> resources) is deferred to a later phase.