Merge pull request #462 from samcharles93/refactor/sqlite-task-store

refactor(store): replace legacy persistence with SQLite
This commit is contained in:
sam authored and GitHub committed 2026-08-09 22:30:44 +10:00
commit 79256fc9fd
170 files changed
+1040 -7612

No files matched your search

@@ -40,8 +40,8 @@ Resolve apparent disagreement in this order:
5. Stop and use `archie-architecture-planning-campaign` if a required semantic
decision remains open.
Route to `archie-domain-reference` for glossary, `archie-nelldb` for
persistence, `archie-config-and-flags` for config enumeration.
Route to `archie-domain-reference` for glossary and
`archie-config-and-flags` for config enumeration.
## Know the CURRENT system
@@ -191,7 +191,7 @@ Source: `docs/architecture/configuration.md`.
| Capability-specific plugin behavior | Owning domain's typed registry/manager | Never add behavior to `plugin.Plugin`. |
| Broker-neutral publication/subscription mechanics | `internal/eventbus` | Keep message meaning and schemas with their domain. |
| Shared policy evaluation/evidence mechanics | `internal/policy` | Keep policy vocabulary, evaluators, and consequences with consuming domain. |
| NATS, SQLite/NellDB, forge, config decoding, external SDK adapters | `internal/infrastructure/<capability>` | Implement a narrow owner-defined contract; translate at boundary. |
| NATS, SQLite, forge, config decoding, external SDK adapters | `internal/infrastructure/<capability>` | Implement a narrow owner-defined contract; translate at boundary. |
| Construction, cross-domain connection, startup/shutdown | `internal/app/archied` or `internal/app/agentworker` | Keep `cmd/*` thin; define health and shutdown order. |
| Deploy assembly | `deployments/<assembly>` | Do not move application behavior into deployment files. |
| Unreviewed memory/tools/workspace/gate/storage/web/RPC/scheduling | **OPEN** | Run `archie-architecture-planning-campaign`. |
+2 -2
View File
@@ -170,8 +170,8 @@ builder tags omit patch/digest; Ubuntu base images omit digests; agent installs
multiple `@latest` Go tools; Node from moving `setup_24.x` channel.
`task docker-build` needs registry/network and functioning Compose.
`task docker-up` additionally pulls images, binds ports 4222/8222/8484, mounts
host paths and container socket.
`task docker-up` starts the Compose-managed NATS service and binds ports
4222/8222. The host daemon and its Docker-socket access are outside Compose.
## Separate environment failures from code failures
@@ -66,10 +66,10 @@ Start at these verified anchors:
| Sandboxed worker | `cmd/archie-agent/main.go`, `cmd/archie-agent/taskrun.go` |
| Task orchestration | `internal/daemon/daemon.go`, `internal/workflow/` |
| Task contracts and SQLite | `internal/store/interface.go`, `internal/store/` |
| Production task persistence | `internal/nell/adapter.go`; `nell.OpenStore` in `cmd/archied/main.go` |
| Production task persistence | `internal/store/`; `store.Open` in `cmd/archied/main.go` |
| RPC split | `internal/{nats,taskrun,natsrpc,storerpc,forgerpc,worktreerpc}/` |
| Chat and channels | `internal/gateway/`, `internal/channels/` |
| Configuration | `internal/config/`, `config.example.toml`, `config.docker.toml` |
| Configuration | `internal/config/`, `internal/infrastructure/configuration/`, `config.example.toml`, `deployments/*.toml` |
| Target map | `docs/prds/01-project-management.md` and linked `docs/architecture/*.md` |
## Use syntax, type, and call evidence
@@ -181,19 +181,15 @@ test-only.
6. Read contract/architecture tests.
7. Confirm deploy inputs in Compose and CI.
### Trace NellDB without guessing
### Trace SQLite persistence
Treat `internal/store` as application contract, `internal/nell` as one adapter.
Treat `internal/store` as the application contract and production adapter.
```sh
go doc github.com/samcharles93/NellDB.Store
gopls implementation internal/store/interface.go:16:6
rg -n 'sdk\.New|\.Get\(|\.Put\(|AllDocs|taskKey|docToTask|taskFields' internal/nell
rg -n 'CREATE TABLE|CREATE INDEX|QueryContext|ExecContext|BeginTx' internal/store
```
As of 2026-07-28, `Adapter.Transition` neither locks nor checks `from`. NellDB's
`_id`/`_rev`, HLC, and conflict semantics come from the dependency API.
## Reject false confidence
| Weak evidence | Why it fails | Required correction |
@@ -1,6 +1,6 @@
---
name: archie-config-and-flags
description: Trace, add, rename, deprecate, or debug Archie configuration and command-line flags from external input through defaults, validation, overlays, environment and secret handling, worker snapshots, deployment passthrough, and the production consumer. Use for internal/config, config.example.toml, config.docker.toml, docker-compose.yml, archied or archie-agent flags, multi-identity settings, mode-parity questions, and reports of a setting that parses but has no effect.
description: Trace, add, rename, deprecate, or debug Archie configuration and command-line flags from external input through defaults, validation, overlays, environment and secret handling, worker snapshots, deployment passthrough, and the production consumer. Use for internal/config, config.example.toml, deployments/*.toml, docker-compose.yml, archied or archie-agent flags, multi-identity settings, mode-parity questions, and reports of a setting that parses but has no effect.
---
# Trace Archie configuration and flags
@@ -34,7 +34,7 @@ Never upgrade a status merely because decoding tests pass.
5. Find the production composition site and final behavior-changing read.
6. Find tests for decoding, defaulting, invalid input, production composition,
and mode parity.
7. Check `config.example.toml`, `config.docker.toml`, `docker-compose.yml`, and
7. Check `config.example.toml`, `deployments/*.toml`, `docker-compose.yml`, and
deployment environment passthrough.
8. Assign one status from the table above.
@@ -49,13 +49,13 @@ rg -n 'FIELD_NAME|external_key|ENV_NAME' \
| Input path | Current behavior | Status |
| --- | --- | --- |
| `archied -config PATH` | Defaults to `$XDG_CONFIG_HOME/archie/config.toml`, or `$HOME/.config/archie/config.toml`; `cmd/archied/main.go` calls `config.LoadOverlay`. | production-wired |
| `archied -config-overlay PATH` | Decodes base TOML, then overlay TOML into the same `Config`, calls `finalize` once. Omitted overlay fields retain base values. | production-wired |
| `archied -config PATH` | Defaults to `$XDG_CONFIG_HOME/archie/config.toml`, or `$HOME/.config/archie/config.toml`; `cmd/archied/main.go` calls `configuration.Loader.Resolve`. | production-wired |
| `archied -config-overlay PATH` | Resolves a file or directory overlay through the same loader. Omitted overlay fields retain base values. | production-wired |
| `config.Load(PATH)` | Loads one TOML and finalizes it; no current binary calls it directly. | test/library-only |
| `config.LoadDir(base, overlay)` | Supports main YAML/TOML plus feature YAML and `conf.d`; no current entrypoint calls it. | test/library-only |
| `config.example.toml` | Load-tested example, not a deployed configuration. | test/library-only |
| `config.docker.toml` | Repository overlay mounted by Compose; still depends on host base config. | production-wired |
| Host base config and environment on `carina` | Mounted from `${HOME}/.config/archie/config.toml`; contents absent from this repository. | external-production-unknown |
| `deployments/docker-nats-stack.toml` | Complete host-daemon configuration for the Compose-managed NATS service. It is copied into the operator's config directory; Compose does not mount it. | supported-example |
| Operator config and environment | Lives outside the repository; contents are deployment-specific. | external-production-unknown |
Both TOML and YAML decoding are non-strict at the field level. Add explicit
compatibility and typo tests; never use "the file loaded" as evidence that a
@@ -96,7 +96,7 @@ Do not expose these helper flags as daemon settings.
| Keys | Default, validation, and consumer | Status |
| --- | --- | --- |
| `work_dir`, `db_path` | Derive from `$XDG_DATA_HOME/archie`, else `$HOME/.local/share/archie`; literal `~` in explicit value not expanded. | production-wired |
| `work_dir`, `db_path` | Derive from `$XDG_DATA_HOME/archie`, else `$HOME/.local/share/archie`; explicit `~` paths are home-expanded. `db_path` is a prefix: tasks/events use `<db_path>-tasks.sqlite` and conversations use `<db_path>-conversations.sqlite`. | production-wired |
| `skills_dir` | Empty falls back to `work_dir` for startup workflow registry. | partially-wired |
| `plugin_dir` | Empty disables daemon plugin loading; configured directory loaded in `cmd/archied`. | production-wired |
| `poll_interval` | Default `60s`; root poll loop uses it, identities may override only interval. | production-wired |
@@ -213,9 +213,8 @@ identity: identity forges require explicit structured `token`.
`cmd/archied` creates `secret.NewRegistry`, which registers only the `env`
engine. Non-env `SecretRef` values are not production-wired.
Compose passes only `ARCHIE_GITEA_TOKEN`,
`ARCHIE_GITEA_TOKEN_ARCHIE`, `HEYARCHIE_TELEGRAM_BOT_TOKEN`, and
`DEEPSEEK_API_KEY` into `archied`.
The host supervisor or launch shell supplies daemon secrets. Compose supplies
no `archied` environment because the daemon is not a Compose service.
## Follow the approved target
@@ -1,6 +1,6 @@
---
name: archie-debugging-playbook
description: Project-specific symptom-to-evidence triage for archie-core. Load this skill when Archied hangs, parks a task, loses or duplicates work, cannot reach NATS or an agent container, rejects configuration or secrets, shows stale Telegram or dashboard state, loses streamed text, fails MCP startup, reports NellDB state surprises, degrades an optional feature, or when Go tests disagree between a sandbox, editor, CI, and the host. Use it to separate environment failures from code regressions and to choose the next exact diagnostic.
description: Project-specific symptom-to-evidence triage for archie-core. Load this skill when Archied hangs, parks a task, loses or duplicates work, cannot reach NATS or an agent container, rejects configuration or secrets, shows stale Telegram or dashboard state, loses streamed text, fails MCP startup, reports SQLite state surprises, degrades an optional feature, or when Go tests disagree between a sandbox, editor, CI, and the host. Use it to separate environment failures from code regressions and to choose the next exact diagnostic.
---
# Debug Archie from evidence
@@ -39,7 +39,7 @@ Use this symptom index:
| Telegram reply hangs on the first token | Stream consumer | Streaming |
| MCP unit tests pass but a real server hangs | Framing mirror | MCP |
| Telegram shows old commands | Token-scoped Telegram state | Telegram |
| Transition succeeds from the wrong state | Store semantics | NellDB/state |
| Transition succeeds from the wrong state | Store semantics | SQLite/state |
| Dashboard skips events but task state is correct | Bounded event buffers | Events |
| Search works but never becomes indexed | Missing production wiring | Optional features |
| Agent container cannot resolve `nats` | Docker network | Containers |
@@ -98,7 +98,7 @@ commit `308c199`, not proof that Yaegi cannot run external commands.
```bash
docker compose ps
docker compose logs --since=10m archied nats
docker compose logs --since=10m nats
docker compose exec -T nats wget -q -O - http://localhost:8222/healthz
```
@@ -138,7 +138,8 @@ env GOTMPDIR=/tmp GOCACHE=/tmp/archie-config-gocache \
composition-root read is a wiring gap, not a parser bug.
For environment failures:
- Compose passes only the names listed under `archied.environment`.
- The host supervisor supplies the daemon environment; inspect its unit or
launch environment rather than Compose.
- `containerEnv` translates configured NATS token name into `NATS_TOKEN` and
forwards configured provider key variables.
- `SubprocessRunner` forwards default compatibility variables, configured
@@ -195,13 +196,13 @@ env GOTMPDIR=/tmp GOCACHE=/tmp/archie-telegram-gocache \
## Diagnose state, events, containers, and optional features
### NellDB and transitions
`internal/nell.Adapter.Transition` writes `to`, ignores `from` and `detail`.
### SQLite and transitions
`internal/store.Store.Transition` owns task state changes and transition history.
When state is surprising: read `TaskByID` before/after caller; trace every
`Transition`, `Requeue`, `RecoverStale`, `Update`.
```bash
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-state-gocache go test ./internal/nell ./internal/store -count=1
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-state-gocache go test ./internal/store -count=1
```
### Events
@@ -165,17 +165,17 @@ no dead-code analyzer.
## Collect test, race, coverage, and runtime evidence
```sh
go test ./internal/nell -count=1 -coverprofile=/tmp/archie-nell.cover
go tool cover -func=/tmp/archie-nell.cover
go test -race ./internal/nell -count=1
go test ./internal/store -count=1 -coverprofile=/tmp/archie-store.cover
go tool cover -func=/tmp/archie-store.cover
go test -race ./internal/store -count=1
```
As of 2026-07-28, the package reported 65.2% statement coverage and passed its
race run.
```sh
docker compose logs archied >"$evidence_dir/archied.log"
docker compose logs nats >"$evidence_dir/nats.log"
journalctl --user -u archied >"$evidence_dir/archied.log"
curl -fsS http://localhost:8222/healthz >"$evidence_dir/nats-health.txt"
```
@@ -61,7 +61,7 @@ scan_literal gitea_container_publish gitea-workflows 'docker build|docker push'
scan_literal production_load_overlay composition-root 'config\.LoadOverlay\(' cmd/archied/main.go
scan_literal production_load_dir composition-root 'config\.LoadDir\(' cmd/archied/main.go
scan_literal production_nell_store composition-root 'nell\.OpenStore\(' cmd/archied/main.go
scan_literal production_sqlite_store composition-root 'store\.Open\(' cmd/archied/main.go
scan_literal production_daemon composition-root '&daemon\.Daemon\{' cmd/archied/main.go
scan_literal production_rpc_servers composition-root 'registerTaskRPCServers\(' cmd/archied/main.go
@@ -1,6 +1,6 @@
---
name: archie-domain-reference
description: "Use when naming, designing, reviewing, documenting, tracing, or migrating Archie concepts such as Agent, Identity, user, Message, Conversation, work intake, WorkflowExecution, plugin engines, channels, events, policy, forge, worktrees, or gates; when current task/gateway/store vocabulary conflicts with the approved architecture; or when a feature risks crossing domain ownership boundaries. Provides project-specific current-to-target mappings, ownership rules, lifecycle language, and glossary checks. Do not use for NellDB API mechanics, general code tracing, config enumeration, debugging, or operations."
description: "Use when naming, designing, reviewing, documenting, tracing, or migrating Archie concepts such as Agent, Identity, user, Message, Conversation, work intake, WorkflowExecution, plugin engines, channels, events, policy, forge, worktrees, or gates; when current task/gateway/store vocabulary conflicts with the approved architecture; or when a feature risks crossing domain ownership boundaries. Provides project-specific current-to-target mappings, ownership rules, lifecycle language, and glossary checks. Do not use for database API mechanics, general code tracing, config enumeration, debugging, or operations."
---
# Archie Domain Reference
@@ -134,7 +134,6 @@ If current behavior differs from chronicle, update the packet.
| Memory scrubber `Flush` leak, 2026-07-26 | Stream ending inside `...secret</mem` emits buffered hidden memory to visible response. | Pending bytes did not retain whether captured inside `<memory>` block. | `b4aaaf0`. **Settled.** Test every streaming state at EOF. Flush is security boundary. |
| Linter autofix shadowing, 2026-07-28 | 24-file "style" pass stops compiling. | `gocritic` changed `ctx, cancel = context.WithTimeout(...)` to `:=` inside conditional, shadowing context. | `9b44bac`. **Settled.** Treat autofix output as authored behavior. |
| All eleven `nilerr` findings semantic false positives, 2026-07-28 | Mechanical "fixes" would return Go errors while tests pass, breaking model correction, chat, NATS envelopes, clean shutdown, indexing. | Linter cannot see failures carried as text, envelopes, shutdown signals, or skipped entries. | `86cfc19`. **Settled.** Review semantic channels one site at a time. |
| NellDB local replace broke delivery, 2026-07-26 to 2026-07-27 | Every CI Docker build fails `go mod download` on `/work/apps/nell-engine`. | Local `replace` paths don't exist in CI/build contexts. | `07fb291` removes replace. **Settled.** Never commit machine-local `replace` directives. |
| Broad checkpoint hid unresolved merge conflict, 2026-07-27 | Literal conflict marker reached committed source. | Unrelated surfaces combined without whole-diff conflict scan. | `4429ae5`. **Settled.** Keep commits cohesive. |
### Preserve the eight tool-registry review lessons
-229
View File
@@ -1,229 +0,0 @@
---
name: archie-nelldb
description: >-
Maintain, debug, review, or migrate Archie's current NellDB-backed
persistence. Load this skill when touching internal/nell, store.TaskStore,
db_path, the tasks/events/sessions/messages collections, persisted task or
event fields, document IDs, _rev or HLC conflicts, scans and ordering,
restart recovery, SQLite-to-NellDB compatibility, backfills, or the pinned
NellDB dependency; also load it when tasks, events, identities, or chat
history disappear, duplicate, reorder, fail to transition, or fail to
survive restart.
---
# Archie NellDB
Treat Archie's database as domain state behind an application adapter.
Stop for architecture planning when the change defines atomic
state-plus-event persistence or WorkflowExecution storage — OPEN decisions.
## Use the vocabulary precisely
| Term | Meaning in this repository |
| --- | --- |
| `store.TaskStore` | Archie's application-facing task, query, event, and lifecycle interface in `internal/store/interface.go`. |
| NellDB engine | The pinned `github.com/samcharles93/NellDB` `Store` layer: records, collections, HLC ordering, conflict resolution, and storage backends. |
| `LogStore` | NellDB's persistent append-only, Zstd-framed implementation opened by `logstore.OpenLog`. |
| `sdk.DocDB` | NellDB's document adapter over one named collection. Maps `sdk.Doc` values to engine records. |
| Collection | A namespace in the engine. Engine key is `collection + ":" + record ID`. |
| Document ID | The application key stored in reserved field `_id`; distinct from `store.Task.ID`. |
| Revision (`_rev`) | SDK MVCC token of form `<generation>-<sha1>`. Detects stale local document writes. |
| HLC | NellDB's hybrid logical clock: Unix milliseconds plus logical counter. |
| Node ID | Writer string stamped into `UpdatedBy`. Archie passes `cfg.BotUser`. |
| LWW | Engine-level last-write-wins: higher HLC wins; equal HLC uses lexically larger `UpdatedBy`. |
| Tombstone | Record with `Deleted=true`. Normal `Get`/`List` hides it; remains in append-only log until compaction. |
Never transfer SQL transactions, constraints, `ORDER BY`, WAL, row counts, or
index behavior to NellDB by analogy.
## Establish CURRENT production truth
Verified **2026-07-28**: `config.LoadOverlay` → `cfg.DBPath`/`cfg.BotUser` →
`nell.OpenStore` → `logstore.OpenLog` → one Store with `"tasks"`, `"events"`,
and optionally `"sessions"`/`"messages"` DocDBs.
| Fact | Current evidence | Consequence |
| --- | --- | --- |
| `cmd/archied/main.go` unconditionally opens `nell.OpenStore(cfg.DBPath, cfg.BotUser)`. | `cmd/archied/main.go` | NellDB is the production task/event backend. No runtime backend selector. |
| `internal/store.Store` still implements `TaskStore` using SQLite. | `internal/store/{interface,store,events}.go` | SQLite remains a test implementation; NellDB is the production backend. |
| The same engine is lent to `gateway.NewSessionStore` only inside Telegram wiring. | `cmd/archied/main.go`; `internal/gateway/session_store.go` | Session/message collections exist only when that path writes them. |
| `go.mod` pins `github.com/samcharles93/NellDB v0.2.5` with no `replace`. | `go.mod`; `go.sum` | Review against published v0.2.5 source. |
| Archie does not call NellDB replication, compaction, changes-feed, or vector-search APIs. | No production matches | Do not claim those engine features are active. |
Verify dependency:
```bash
go list -m -f '{{.Path}} {{.Version}}{{if .Replace}} => {{.Replace.Path}} {{.Replace.Version}}{{end}}' github.com/samcharles93/NellDB
rg -n '^replace .*NellDB|github.com/samcharles93/NellDB' go.mod go.sum
go list -m -f '{{.Dir}}' github.com/samcharles93/NellDB
```
Expected: `github.com/samcharles93/NellDB v0.2.5`. If a `=> /local/path` suffix
appears, stop. Commit `07fb291` removed exactly that failure mode.
## Separate engine guarantees from Archie guarantees
| Concern | NellDB v0.2.5 proves | Archie currently adds or fails to add |
| --- | --- | --- |
| Concurrency | `MemoryStore`, `LogStore`, and `DocDB` protect individual calls with mutexes. | `Adapter.mu` serializes selected multi-call operations in one adapter instance only. |
| Document conflicts | Stale `_rev` to `DocDB.Put` returns `sdk.ErrConflict`. | Adapter helpers usually re-read before `Put`; can avoid conflict while copying stale application fields. |
| Cross-node conflict | Engine `Put` applies HLC LWW, then lexical `UpdatedBy` tie-break. | No Archie replication path is wired. |
| Persistence | Default `OpenLog` appends a frame and flushes buffered writer on each write. Close flushes again. | Archie defers one adapter close. No checkpoint, snapshot, or compaction service wired. |
| Crash behavior | Replay rebuilds in-memory index. Incomplete tail frame is ignored. | `Daemon.Startup` separately calls `RecoverStale`, changing every `running` task to `queued`. |
| Power loss | Neither default flush nor group commit calls `fsync`. | Archie adds no explicit sync. |
| Deletes | `Remove` writes a tombstone; ordinary list/get hide it. | `ClearTerminalTasks` tombstones terminal task documents. File space not reclaimed (no compaction). |
| Queries | Engine indexes collection membership and HLC changes. `Query` is a collection-list stub. | Adapter performs field queries by collection scans. Gateway message search uses substring matching. |
| Listing | `AllDocs` returns a snapshot filtered after `Store.List`; range results not sorted by key. | Task/event methods sort when contract needs it. Session/message code assumes ordering where SDK does not guarantee it. |
| Node identity | Records retain their `UpdatedBy`; conflict resolution uses it. | `LogStore.NodeID()` returns value passed to current open. Changing `bot_user` changes future writer identity. |
Do not open the same log file from multiple processes or adapter instances.
No cross-process lock or supported multi-writer assembly is proven.
## Know the stored shapes
### Collections and keys
| Collection | Document ID | Application data | Read pattern |
| --- | --- | --- | --- |
| `tasks` | `<owner>:<repo>:<issue_number>` | Current `store.Task` fields plus `created_at` | Direct `Get` by forge coordinates; scans for numeric task ID, status, claims, counts, stats |
| `events` | `event:<numeric-id>` | `events.Event`; `data` stored as JSON string | Full scan, application filter, explicit ID sort |
| `sessions` | `SessionContext.SessionID` | platform, bot, channel, optional thread, timestamps | Direct `Get`; full scan for list/channel lookup |
| `messages` | `<session-id>:<20-digit-sequence>` | session, sequence, sender, text, channel/thread, timestamp | Collection scan plus key-range filter |
Each `DocDB` may also contain SDK IDs `meta:clock` and `meta:vector`. Archie adds
`meta:task_id_counter` and `meta:event_id_counter`. Adapters skip `meta:` prefix.
Do not create an application ID beginning with `meta:`. `isMetaKey` will also
hide a legitimate task whose composite key begins `meta:` from scan-based claims
and queries, even though direct `Get` can find it. Treat as CURRENT risk.
### Task document mapping
| Group | Fields |
| --- | --- |
| Reserved and local identity | `_id`, SDK-managed `_rev`, numeric `id`, `created_at` |
| Source snapshot | `owner`, `repo`, `issue_number`, `title`, `body`, `labels`, `source`, `identity` |
| Lifecycle | `status`, `attempt`, `retry_count`, `park_reason`, `watch_comment_id` |
| Workflow/output | `workflow`, `stage`, `branch`, `plan`, `notes`, `pr_number`, `tokens_used`, `iterations` |
Conversion rules:
- Store numeric fields as `int64`. `intField` accepts `float64`, `int64`,
`int`, and `json.Number`.
- Treat missing `source` as `forge`; `sourceOrDefault` preserves old documents.
- Preserve `_id` and `_rev` by starting updates from `DocDB.Get`.
- Keep workflow `Update` restricted to its documented mutable subset.
CURRENT defect: `EnqueueIssue` accepts `identity` but does not put `identity`
into the Nell document. Forge tasks read back with empty identity.
`EnqueueChatTask` does write both `source=chat` and `identity`.
### Event document mapping
`InsertEvent` stores: `id, at, kind, task_id, repo, issue, workflow, stage,
detail, data`. Clips `detail` to 4000 bytes without splitting UTF-8 rune.
Serializes `data` to JSON string; substitutes `marshal_error` on failure.
`docToEvent` ignores invalid timestamps and invalid `data` JSON.
Events are observability records, not atomic task-transition history. Nell
`Transition` ignores `detail`, and the event sink writes asynchronously.
## Audit lifecycle and atomicity before editing
| Operation | Current serialization | Important limit |
| --- | --- | --- |
| `ClaimNext`, `ClaimByIssue` | Scan/get + write under `Adapter.mu` | Atomic only with same mutex on same instance. |
| Task/event ID allocation | Counter RMW under `Adapter.mu` | Enqueue duplicate check outside critical section. |
| `RecoverStale`, `ClearTerminalTasks` | Full scan + writes under `Adapter.mu` | `Transition`, `Update`, `Requeue` do not take mutex. |
| `Transition` | Find by ID, set `Status`, put | Ignores `from`/`detail`; writes no transition record; no lock. |
| `Requeue` | Find, mutate fields, put | Ignores `fromStatus`; writes no transition record; no lock. |
| `Update` | Get by key, replace allowed fields, put | One doc write, no domain state/event transaction. |
| `IncrementRetryCount` | Find, increment, put | Multi-call RMW without adapter lock. |
| `InsertEvent` | ID allocation + put under `Adapter.mu` | Separate from state mutation that caused event. |
`Transition` does not make a state machine. Target must compare expected
state/version, enforce legal transitions, commit state with domain event at one
atomic boundary.
## Investigate without damaging the log
```bash
rg -n 'OpenStore|NewSessionStore|TaskStore|DBPath' cmd/archied internal
rg -n 'func \\(a \\*Adapter\\)|sdk\\.New|AllDocs|FieldID|isMetaKey' internal/nell/adapter.go
rg -n 'SaveMessage|RecentMessages|SearchMessages|sdk\\.New' internal/gateway/session_store.go
rg -n 'store\\.Open\\(|nell\\.OpenStore\\(' --glob '*.go'
```
Inspect a configured file without opening it:
```bash
: "${DB_PATH:?set DB_PATH from the running config's db_path field}"
test -r "$DB_PATH" && test -f "$DB_PATH"
file -- "$DB_PATH"
od -An -tc -N16 -- "$DB_PATH"
stat -- "$DB_PATH"
```
Never run `sqlite3 "$DB_PATH"` because the name ends in `.db`. A current
NellDB file is a Zstd-framed binary append log. Never pass a legacy SQLite file
to `nell.OpenStore`; there is no format detector or automatic migration.
```bash
go test ./internal/nell -run '^(TestEnqueueIdempotent|TestChatTaskLifecyclePreservesRouting|TestPersistenceAcrossRestart|TestConcurrentEnqueueAndClaim)$' -count=1
go test -race ./internal/nell ./internal/gateway -count=1
go test ./internal/store ./internal/nell -count=1
go test ./cmd/archied -run '^TestChatTaskCommandsEndToEnd$' -count=1
```
As verified 2026-07-28, these pass with writable Go caches.
## Change persisted data safely
- Trace every producer, converter, reader, projection, RPC payload, test
backend, and production constructor. State what new data supersedes.
- Add red tests with old/missing fields. Test round-trips for forge and chat.
- Update creation paths, `docToTask`, `taskFields`, and restricted `Update` set.
- Preserve `_id`/`_rev`; never delete `_rev` to "fix" conflicts.
- Give missing/legacy data explicit compatibility rules.
- Check SQLite implementation deliberately — contract parity or proven cutover.
- Test field preservation through all lifecycle operations and reopen.
- Add stale-revision, concurrent-writer, cancellation, malformed-value, restart cases.
- Measure scans at representative sizes before accepting another scan.
- Use shared backend contract test suite for `TaskStore` changes.
## Gate migration and backfill explicitly
There is no repository-supported SQLite-to-NellDB migration or backfill command
as of 2026-07-28.
Before any cutover:
1. Freeze authoritative source or define proven dual-write protocol.
2. Keep SQLite input and NellDB output at different paths.
3. Inventory task rows, IDs, coordinates, statuses, fields, events, transition history.
4. Decide where transition history goes; build dry-run exporter/importer with
deterministic IDs, idempotent writes, checkpoints, rejection reporting.
5. Compare counts by status/source/workflow plus content digests.
6. Quiesce, copy, convert, validate, switch `db_path` once.
7. Retain untouched source and last-known-good binary/config until window passes.
8. Delete old reader only after production wiring, rollback, and change control.
Treat NellDB `PutMany` as sequential engine writes, not crash-atomic.
Its SDK cache rollback does not undo records already written.
## Triage by symptom
| Symptom | Prove first | Likely CURRENT seam |
| --- | --- | --- |
| `nell: path is required` | Trace `cfg.DBPath` and direct caller. | `OpenStore` rejects empty path. |
| `nell: open log: ... no such file or directory` | Check parent directory, mount, UID, `db_path`. | `OpenStore` does not create parent directory. |
| Old tasks vanish after backend switch | Inspect file signature and configured path. | No SQLite import or format check. |
| Forge task identity empty after reload | Compare enqueue args with Nell document constructor. | `EnqueueIssue` drops `identity`; chat enqueue does not. |
| Stale/illegal transition succeeds | Read `Transition`, capture before/after state. | `from` unused in both Nell and SQLite. |
| State changed but no matching history/detail | Trace state write and event sink independently. | Nell transition history absent; event persistence async. |
| Directly addressable queued task never claimed | Check if document ID begins `meta:`. | Scan paths filter every `meta:` prefix. |
| Recent messages reorder or omit turns | Test more than one insertion order and restart. | `RecentMessages` assumes key-sorted `AllDocs`; v0.2.5 not sorted. |
| `sdk: revision conflict` | Preserve conflicting docs/revisions. | Stale explicit `_rev` supplied. |
| Database grows after updates/deletes | Compare file size with document counts. | Append-only tombstones accumulate; no compaction. |
| Data survives restart but not power loss | Separate close/replay from storage durability. | Default writes flush but don't `fsync`. |
| NellDB SDK tests fail on `server/webui/dist/nell.wasm` | Run Archie's focused packages. | Published v0.2.5 omits embedded WASM asset. |
| Fix on another branch; main still fails | Inspect current source and branch containment. | Candidate code is not live behavior. |
@@ -1,4 +0,0 @@
interface:
display_name: "Archie NellDB"
short_description: "Maintain Archie persistence on NellDB safely"
default_prompt: "Use $archie-nelldb to inspect or change Archie persistence without importing SQLite assumptions."
+22 -22
View File
@@ -1,6 +1,6 @@
---
name: archie-run-and-operate
description: "Run and observe Archie safely from a local binary or the repository Docker Compose stack. Use when starting or stopping archied, running an archie-agent NATS worker, checking readiness, following logs, locating task state/worktrees/memory/container volumes, understanding inprocess/subprocess/NATS execution, inspecting the deployment watcher or image pipeline, or planning an operational rollback without changing architecture."
description: "Run and observe Archie safely with a host daemon and the repository's Docker Compose NATS service. Use when starting or stopping archied, running an archie-agent NATS worker, checking readiness, following logs, locating task state/worktrees/memory/container volumes, understanding inprocess/subprocess/NATS execution, inspecting the image pipeline, or planning an operational rollback without changing architecture."
---
# Run and operate Archie
@@ -12,12 +12,12 @@ Treat source and tests as current; treat `docs/archive/` as history.
| Term | Meaning here |
|---|---|
| `archied` | Resident orchestrator. Owns config, forge credentials, NellDB store, worktrees, gateways, dashboard, optional NATS/Docker orchestration. |
| `archied` | Resident orchestrator. Owns config, forge credentials, SQLite stores, worktrees, gateways, dashboard, optional NATS/Docker orchestration. |
| `archie-agent` | Long-running NATS worker. Consumes per-stage `archie.agent.>` requests and full-task `archie.taskrun.>` requests. Not a stdin/stdout worker. |
| Stage request | One autonomous workflow stage sent on `archie.agent.<task-id>.request`. |
| Full-task handoff | A whole workflow sent on core NATS subject `archie.taskrun.<task-id>` to a task container. |
| Work directory | `work_dir`: task clones plus memory and candidate index artifacts. |
| State database | `db_path`: the NellDB append-log file holding tasks, events, and Nell-backed chat sessions/messages. Not SQLite despite the `.db` examples. |
| State path prefix | `db_path`: the configured prefix. Task/event state uses `<db_path>-tasks.sqlite`; conversation state uses `<db_path>-conversations.sqlite`. |
## Apply the operational safety boundary
@@ -64,10 +64,10 @@ Both linked binaries may also display Go's `-quickchecks` flag from
| Config shape | What runs | Operational status on 2026-07-28 |
|---|---|---|
| `agent.mode = "inprocess"` and no `[nats]` | `archied` polls and claims from NellDB, runs workflow stages and model tools in-process. | **Production-wired candidate.** No process or OS isolation. |
| `agent.mode = "inprocess"` and no `[nats]` | `archied` polls and claims from SQLite, runs workflow stages and model tools in-process. | **Production-wired candidate.** No process or OS isolation. |
| `agent.mode = "subprocess"` | `archied` starts `agent.command` per stage and expects one JSON invocation on stdin, one response on stdout. | **Open/broken with default command.** `cmd/archie-agent` is a long-running NATS worker and never calls `agentexec.ServeOne`. |
| `agent.mode = "nats"`, `[nats]`, containers disabled | `archied` runs the workflow; each autonomous stage goes to a separately started `archie-agent`. | **Implemented but operator-assembled.** Launch and supervise a worker separately. |
| `agent.mode = "nats"`, `[nats]`, `containers.enabled = true` | `archied` publishes task discovery through JetStream, prepares a worktree, spawns one agent container, sends the whole workflow on `archie.taskrun.<id>`. | **Repository Compose path.** `config.docker.toml` wires it. |
| `agent.mode = "nats"`, `[nats]`, `containers.enabled = true` | `archied` publishes task discovery through JetStream, prepares a worktree, spawns one agent container, sends the whole workflow on `archie.taskrun.<id>`. | **Host daemon + Compose NATS path.** `deployments/docker-nats-stack.toml` demonstrates it. |
## Run a local foreground daemon
@@ -94,7 +94,7 @@ startup did not complete. The daemon has no HTTP health endpoint.
Stop with `Ctrl-C`. The signal cancels active work, waits for dispatch
goroutines, stops capability and memory managers, removes Archie-labelled
containers, closes NATS, and closes the NellDB log.
containers, closes NATS, and closes the SQLite stores.
## Run a standalone NATS worker
@@ -110,21 +110,20 @@ Do not use this to test subprocess mode.
| Repository command | Actual scope |
|---|---|
| `task docker-build` | Build only the `agent` image from `Dockerfile`. |
| `task docker-up` | Run `docker compose up -d` for **all** services, including watchtower. |
| `task docker-logs` | Follow only the `archied` service logs. |
| `task docker-up` | Start the Compose-managed NATS service. The profiled agent entry is not started. |
| `task docker-logs` | Follow the NATS service logs. |
| `task docker-down` | Run `docker compose down`. Does not request volume deletion. |
Prefer the narrow start:
```bash
docker compose up -d nats archied
docker compose up -d nats
```
Read-only observations:
```bash
docker compose ps
docker compose logs --tail=200 archied
docker compose logs --tail=200 nats
docker compose exec -T nats wget -q -O - http://localhost:8222/healthz
```
@@ -134,8 +133,9 @@ curl -fsS http://127.0.0.1:8484/api/summary
curl -fsS http://127.0.0.1:8484/api/tasks
```
The NATS healthcheck must become healthy before Compose starts `archied`.
Require `archied running` in logs as the daemon readiness gate.
Wait for the NATS healthcheck, then start `archied` on the host. Require the
configured host supervisor to report it running and verify the dashboard API
as the daemon readiness gate.
Stop with:
@@ -144,16 +144,17 @@ task docker-down
```
Never add `-v` during routine shutdown. The Compose `agent` service is a
build-only placeholder that clears the image entrypoint and runs `true`.
Actual task workers are spawned by `archied` through `/var/run/docker.sock`.
build-profile image definition, not a long-running service. Actual task workers
are spawned by the host `archied` process through `/var/run/docker.sock`.
## Locate output and durable state
| Output or state | Current destination |
|---|---|
| Daemon logs | JSON on stderr; Docker's configured log driver captures them under Compose. |
| Daemon logs | JSON on host stderr; the configured host supervisor captures them. |
| Agent logs | JSON on worker/container stderr. Task containers use `AutoRemove`. |
| Tasks, events, chat sessions/messages | NellDB append log at `db_path`; default `~/.local/share/archie/archie.db`. |
| Tasks and events | SQLite database at `<db_path>-tasks.sqlite`; default `~/.local/share/archie/archie.db-tasks.sqlite`. |
| Chat sessions and messages | SQLite database at `<db_path>-conversations.sqlite`. |
| Default task worktree | `<work_dir>/<owner>-<repo>/issue-<number>`; default root `~/.local/share/archie/work`. |
| Identity worktree | `<work_dir>/identity-<identity>/<owner>-<repo>/issue-<number>`. |
| Container worktree | Host worktree bind-mounted read/write at `/data/worktree`; `task.json` written under `.git/` so the agent's commit cannot sweep it onto the task branch. |
@@ -164,9 +165,9 @@ Actual task workers are spawned by `archied` through `/var/run/docker.sock`.
| Ecosystem cache volumes | `archie-cache-go`, `archie-cache-node`, etc., mounted below `/data/cache`. No code sets tool cache env vars to those mount paths. |
| NATS data | Compose declares `nats_data:/data`; NATS command does not set a store directory. |
In Compose, host paths are: `/var/lib/archie/work` for worktrees;
`/var/lib/archie/db/archie.db` for the container's `/var/lib/archie/archie.db`;
repository checkout mounted at `/workspace`; host Docker socket mounted into `archied`.
Compose runs NATS only; `archied` and all configured state paths remain on the
host. The host daemon talks to the local Docker socket directly and bind-mounts
each task worktree into the agent container it creates.
## Understand NATS and container observation
@@ -180,7 +181,7 @@ for `archie.task.>` and `archie.agent.>`.
| Container task | Core NATS request/reply on `archie.taskrun.<id>`. Task container reads `/data/worktree/.git/task.json` and creates dedicated subscription; shared worker uses queue group `archie-taskrun-workers`. |
| Privileged RPC | Store, forge, and worktree operations return to `archied` over core NATS subjects in `internal/storerpc`, `internal/forgerpc`, and `internal/worktreerpc`. |
Set `containers.network` explicitly. `config.docker.toml` uses
Set `containers.network` explicitly. `deployments/docker-nats-stack.toml` uses
`archie-core_default`. Auto-detection inspects the daemon container; on failure,
workers join Docker's default bridge and cannot resolve `nats`. Initial
`ErrNoResponders` is retried for 20s at 250ms intervals.
@@ -210,7 +211,7 @@ It injects component versions into labels/metadata but publishes no versioned
tags. It runs no quality gate before Docker builds.
Before promotion: record running image IDs/digests; config checksums (no
secrets); task counts via safe GET; establish NellDB backup procedure.
secrets); task counts via safe GET; establish a SQLite backup procedure.
No complete rollback command exists, no versioned image tags. Restoring a binary
does not undo forge changes, task transitions, or data-format changes.
@@ -220,4 +221,3 @@ does not undo forge changes, task transitions, or data-format changes.
Repository guidance (2026-07-28): two instances on `carina` with distinct
`bot_user` values. No live process list, config, image digest, service manager,
or deployment was verified. Do not invent SSH, systemd, or service commands.
+1 -1
View File
@@ -26,7 +26,7 @@ See `docs/architecture/organisation.md` for the target structure and
| `internal/agentexec/` | Versioned agent-stage protocol, worker, and in-process/subprocess runners |
| `internal/forge/` | Forge interface: GitHub and Gitea implementations |
| `internal/worktree/` | Git operations: clone, branch, commit, push, diff, cleanup |
| `internal/store/` | Task store interface; SQLite, RPC client, and nell adapters satisfy it |
| `internal/store/` | Task store interface and SQLite implementation; RPC clients proxy it |
| `internal/events/` | In-process event bus: publish/subscribe for observability |
| `internal/infrastructure/` | Config loading, eventbus transport, model catalog |
| `internal/webui/` | SSE dashboard: live event stream, task status |
+3 -3
View File
@@ -30,8 +30,8 @@
- fix(gateway): resolve the most recently active session, not an arbitrary one
- fix(gateway): give branch-inherited messages their own identity
- fix(gateway): make both backends agree on newest-first
- fix(nell): honour the transition guard on the backend that ships
- fix(nell): move ID counters off the SDK-reserved meta: prefix
- fix(store): honour the transition guard in production persistence
- fix(store): move ID counters away from the reserved metadata namespace
- fix(store): surface task timestamps and tag the summary structs
- fix(telegram): pause the update loop when rate limited
- fix(memory): fail startup on an unusable memory directory
@@ -114,7 +114,7 @@
- feat: add deny-by-default Telegram sender authorization and native command-menu publication
- feat: connect Desktop Commander through Archie's managed MCP client so chat can use workspace file and process tools
- feat: add multi-identity daemon configuration, persona routing, an email channel, and webhook platform support
- feat: add NellDB-backed task, session, message, and memory persistence
- feat: add durable task, session, message, and memory persistence
- feat: add memory synchronization, prefetch, context scrubbing, threat scanning, and built-in memory tools
- feat: add tool guardrails, classification, budgets, availability filtering, and disclosure controls
- feat: add feature-based YAML configuration with `conf.d` overlay loading
+1 -1
View File
@@ -291,7 +291,7 @@ boundaries. Summary of what's evolved since that doc was last fully accurate:
- `internal/channels/` — inbound chat/notification channels (e.g. Telegram — see
`internal/channels/telegram/`, `internal/channels/email/`); channel-agnostic
interface in `internal/channels/channel.go`.
- `internal/memory/`, `internal/nell/`, `internal/gateway/`,
- `internal/memory/`, `internal/gateway/`,
`internal/container/`, `internal/plugin/`, `internal/tools/`,
`internal/taskrun/` — not documented in ARCHITECTURE.md; read the package
before modifying, its doc comment and tests are the source of truth.
+3 -3
View File
@@ -146,7 +146,7 @@ tasks:
- docker compose build agent
docker-up:
desc: Start the archied + NATS stack via docker compose
desc: Start the NATS service via docker compose
cmds:
- docker compose up -d
@@ -156,6 +156,6 @@ tasks:
- docker compose down
docker-logs:
desc: Follow the archied container logs
desc: Follow the NATS container logs
cmds:
- docker compose logs -f archied
- docker compose logs -f nats
+29 -9
View File
@@ -48,7 +48,6 @@ import (
"github.com/samcharles93/archie-core/internal/logging"
"github.com/samcharles93/archie-core/internal/memory"
"github.com/samcharles93/archie-core/internal/memory/builtin"
"github.com/samcharles93/archie-core/internal/nell"
"github.com/samcharles93/archie-core/internal/plugin"
"github.com/samcharles93/archie-core/internal/plugin/pluginextract"
"github.com/samcharles93/archie-core/internal/secret"
@@ -286,6 +285,30 @@ func isForgeDisabled(forgeType string) bool {
}
}
func openProductionTaskStore(ctx context.Context, path string) (store.TaskStore, error) {
return store.Open(ctx, path)
}
func taskDBPath(configuredPath string) string {
return configuredPath + "-tasks.sqlite"
}
func manualRequeueTask(ctx context.Context, st store.TaskStore, taskID int64) error {
task, err := st.TaskByID(ctx, taskID)
if err != nil {
return err
}
if task == nil {
return fmt.Errorf("task %d not found", taskID)
}
switch task.Status {
case store.StatusParked, store.StatusWaitingHuman:
return st.Requeue(ctx, taskID, task.Status, "")
default:
return fmt.Errorf("task %d has status %q; only parked or waiting_human tasks can be requeued", taskID, task.Status)
}
}
func run() int {
defaultCfg := filepath.Join(configHome(), "archie", "config.toml")
cfgPath := flag.String("config", defaultCfg, "path to a TOML/YAML config file or configuration directory")
@@ -293,6 +316,8 @@ func run() int {
once := flag.Bool("once", false, "run a single poll+process cycle and exit (systemd timer / testing)")
requeue := flag.Int64("requeue", 0, "requeue a parked/waiting task by id (keeps its workflow), then exit unless -once is also set")
flag.Parse()
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
log := slog.New(slog.NewJSONHandler(os.Stderr, nil))
@@ -337,7 +362,7 @@ func run() int {
}
forgeClient, token := resolveForge(cfg.Forge, secrets, log)
st, err := nell.OpenStore(cfg.DBPath, cfg.BotUser)
st, err := openProductionTaskStore(ctx, taskDBPath(cfg.DBPath))
if err != nil {
log.Error("open store", "err", err)
return 1
@@ -359,7 +384,7 @@ func run() int {
}()
if *requeue > 0 {
if err := st.Requeue(context.Background(), *requeue, "manual", ""); err != nil {
if err := manualRequeueTask(ctx, st, *requeue); err != nil {
log.Error("requeue failed", "task", *requeue, "err", err)
return 1
}
@@ -369,9 +394,6 @@ func run() int {
}
}
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
catalog, err := modelcatalog.Load(ctx, modelcatalog.Options{
CachePath: filepath.Join(filepath.Dir(*cfgPath), "models.json"),
Getenv: secrets.Getenv,
@@ -1028,16 +1050,14 @@ type chatTaskWriterAdapter struct {
enqueue func(
ctx context.Context,
owner, repo, title, body, workflow, identity string,
issueNumber int,
) (*store.Task, error)
}
func (a chatTaskWriterAdapter) EnqueueChatTask(
ctx context.Context,
owner, repo, title, body, workflow, identity string,
issueNumber int,
) (int64, error) {
task, err := a.enqueue(ctx, owner, repo, title, body, workflow, identity, issueNumber)
task, err := a.enqueue(ctx, owner, repo, title, body, workflow, identity)
if err != nil {
return 0, err
}
+70 -4
View File
@@ -23,7 +23,6 @@ import (
"github.com/samcharles93/archie-core/internal/forgerpc"
"github.com/samcharles93/archie-core/internal/gateway"
"github.com/samcharles93/archie-core/internal/logging"
"github.com/samcharles93/archie-core/internal/nell"
"github.com/samcharles93/archie-core/internal/secret"
"github.com/samcharles93/archie-core/internal/store"
"github.com/samcharles93/archie-core/internal/storerpc"
@@ -318,6 +317,74 @@ func TestConfiguredMCPProviderSupportsAllTransportTypes(t *testing.T) {
}
}
func TestManualRequeueTaskUsesPersistedStatus(t *testing.T) {
tests := []string{store.StatusParked, store.StatusWaitingHuman}
for index, status := range tests {
t.Run(status, func(t *testing.T) {
st, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "tasks.db"))
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = st.Close() })
if _, err := st.EnqueueIssue(t.Context(), "acme", "widget", index+1, "task", "", "", ""); err != nil {
t.Fatal(err)
}
task, err := st.TaskByIssue(t.Context(), "acme", "widget", index+1)
if err != nil || task == nil {
t.Fatalf("TaskByIssue = (%+v, %v)", task, err)
}
if err := st.Transition(t.Context(), task.ID, store.StatusQueued, status, ""); err != nil {
t.Fatal(err)
}
if err := manualRequeueTask(t.Context(), st, task.ID); err != nil {
t.Fatal(err)
}
got, err := st.TaskByID(t.Context(), task.ID)
if err != nil || got == nil || got.Status != store.StatusQueued {
t.Fatalf("TaskByID after requeue = (%+v, %v), want queued", got, err)
}
})
}
}
func TestManualRequeueTaskRejectsOtherStatuses(t *testing.T) {
st, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "tasks.db"))
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = st.Close() })
if _, err := st.EnqueueIssue(t.Context(), "acme", "widget", 1, "task", "", "", ""); err != nil {
t.Fatal(err)
}
task, err := st.TaskByIssue(t.Context(), "acme", "widget", 1)
if err != nil || task == nil {
t.Fatalf("TaskByIssue = (%+v, %v)", task, err)
}
if err := manualRequeueTask(t.Context(), st, task.ID); err == nil {
t.Fatal("manualRequeueTask accepted a queued task")
}
}
func TestChatTaskListerAdapterReadsSQLiteIdentity(t *testing.T) {
st, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "tasks.db"))
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = st.Close() })
want, err := st.EnqueueChatTask(t.Context(), "acme", "widget", "identity task", "", "tdd", "reviewer")
if err != nil {
t.Fatal(err)
}
lister := chatTaskListerAdapter{tasks: st.Tasks}
got, err := lister.ListChatTasks(t.Context(), "reviewer", 10)
if err != nil {
t.Fatal(err)
}
if len(got) != 1 || got[0].ID != want.ID || got[0].Title != want.Title {
t.Fatalf("ListChatTasks = %+v, want task %d", got, want.ID)
}
}
func TestChatTaskWriterAdapter(t *testing.T) {
t.Parallel()
@@ -339,14 +406,13 @@ func TestChatTaskWriterAdapter(t *testing.T) {
enqueue: func(
context.Context,
string, string, string, string, string, string,
int,
) (*store.Task, error) {
return tt.result, tt.err
},
}
id, err := adapter.EnqueueChatTask(
context.Background(),
"owner", "repo", "title", "body", "workflow", "identity", 123,
"owner", "repo", "title", "body", "workflow", "identity",
)
if (err != nil) != tt.wantErr {
t.Fatalf("EnqueueChatTask() error = %v, wantErr %t", err, tt.wantErr)
@@ -546,7 +612,7 @@ func TestChatTaskLogReaderAdapterRoundTrip(t *testing.T) {
func TestChatTaskCommandsEndToEnd(t *testing.T) {
ctx := context.Background()
st, err := nell.OpenStore(filepath.Join(t.TempDir(), "tasks.db"), "test-node")
st, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "tasks.db"))
if err != nil {
t.Fatal(err)
}
+40
View File
@@ -0,0 +1,40 @@
package main
import (
"errors"
"os"
"path/filepath"
"testing"
)
func TestProductionTaskStoreUsesSQLite(t *testing.T) {
configuredPath := filepath.Join(t.TempDir(), "state.db")
path := taskDBPath(configuredPath)
if path == configuredPath {
t.Fatal("task database must use an independent fresh path")
}
st, err := openProductionTaskStore(t.Context(), path)
if err != nil {
t.Fatal(err)
}
if _, err := os.Stat(configuredPath); !errors.Is(err, os.ErrNotExist) {
t.Fatalf("configured anchor path was opened directly: %v", err)
}
inserted, err := st.EnqueueIssue(t.Context(), "acme", "widget", 7, "persisted", "", "", "")
if err != nil || !inserted {
t.Fatalf("EnqueueIssue = (%v, %v), want (true, nil)", inserted, err)
}
if err := st.Close(); err != nil {
t.Fatal(err)
}
st, err = openProductionTaskStore(t.Context(), path)
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = st.Close() })
task, err := st.TaskByIssue(t.Context(), "acme", "widget", 7)
if err != nil || task == nil || task.Title != "persisted" {
t.Fatalf("TaskByIssue after reopen = (%+v, %v)", task, err)
}
}
+2 -3
View File
@@ -11,7 +11,6 @@ import (
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/gateway"
"github.com/samcharles93/archie-core/internal/nell"
"github.com/samcharles93/archie-core/internal/store"
"github.com/samcharles93/archie-core/internal/webui"
)
@@ -43,13 +42,13 @@ func TestDashboardAndChatAgreeOnTerminalStates(t *testing.T) {
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
ctx := context.Background()
st, err := nell.OpenStore(filepath.Join(t.TempDir(), "tasks.db"), "test-node")
st, err := store.Open(ctx, filepath.Join(t.TempDir(), "tasks.db"))
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = st.Close() })
task, err := st.EnqueueChatTask(ctx, "acme", "widget", "decide on me", "", "", "reviewer", 900_001)
task, err := st.EnqueueChatTask(ctx, "acme", "widget", "decide on me", "", "", "reviewer")
if err != nil {
t.Fatal(err)
}
+1 -1
View File
@@ -11,7 +11,7 @@ import (
)
func TestTelegramConversationStoreUsesFreshSQLiteWithoutReadingTaskLog(t *testing.T) {
taskLogPath := filepath.Join(t.TempDir(), "tasks.nell")
taskLogPath := filepath.Join(t.TempDir(), "tasks.db")
taskLog := []byte("not a SQLite database")
if err := os.WriteFile(taskLogPath, taskLog, 0o600); err != nil {
t.Fatalf("write task log fixture: %v", err)
+1 -3
View File
@@ -159,9 +159,7 @@ func makeTelegramSessionStore(cfg config.Config) (gateway.SessionStore, error) {
return gateway.OpenSQLiteSessionStore(conversationDBPath(cfg.DBPath))
}
// conversationDBPath keeps conversation state separate while db_path still
// names the NellDB task log. The suffix is deterministic so the eventual task
// store cutover can open db_path as SQLite without moving conversation data.
// conversationDBPath keeps conversation state in its own SQLite database.
func conversationDBPath(taskDBPath string) string {
return taskDBPath + "-conversations.sqlite"
}
+1 -1
View File
@@ -9,7 +9,7 @@
# secret_engine_dir = "~/.config/archie/secret-engines"
# work_dir = "~/.local/share/archie/work" # default
# db_path = "~/.local/share/archie/archie.db"
# db_path = "~/.local/share/archie/archie.db" # prefix for independent task and conversation SQLite files
poll_interval = "60s"
label = "archie"
+1 -1
View File
@@ -14,7 +14,7 @@ This directory contains configuration templates and guides for different deploym
Self-hosted deployment running local LLM models via Ollama (e.g., `llama3`, `qwen2.5`) with optional standalone (forge-disabled) operation.
* **[`docker-nats-stack.toml`](./docker-nats-stack.toml)**:
The repository's `docker-compose.yml` stack — `archied` orchestrating sandboxed `archie-agent` containers over NATS. Copy to `~/.config/archie/config.toml`; the compose file mounts that path and passes it as the only `-config`.
Host-run `archied` orchestrating sandboxed `archie-agent` containers over the repository's Compose-managed NATS service. Copy to `~/.config/archie/config.toml`, start NATS with Compose, then start `archied` on the host.
* **[`systemd-user-service.md`](./systemd-user-service.md)**:
Operational runbook for running `archied` as a persistent 24/7 background service via systemd user units and `loginctl enable-linger`.
+15 -17
View File
@@ -1,22 +1,21 @@
# Docker Compose + NATS deployment.
# Host daemon + Docker Compose NATS deployment.
#
# Copy to ~/.config/archie/config.toml -- docker-compose.yml mounts that path
# read-only at /etc/archie/config.toml. This is a complete config, not an
# overlay: the stack passes a single -config flag, so nothing in the repo
# working tree needs to exist for the daemon to boot.
# Copy to ~/.config/archie/config.toml. docker-compose.yml starts NATS only;
# run archied on the host (for example with systemd-user-service.md). This is
# a complete config, not an overlay.
#
# mkdir -p ~/.config/archie
# cp deployments/docker-nats-stack.toml ~/.config/archie/config.toml
# docker compose up -d
# docker compose up -d nats
# archied -config ~/.config/archie/config.toml
#
# Paths below are container paths. docker-compose.yml maps them to host
# volumes (/var/lib/archie/work and /var/lib/archie/db).
# Paths below are host paths. Explicit home-relative paths are expanded.
poll_interval = "60s"
bot_user = "archie"
diff_cap_lines = 0
work_dir = "/var/lib/archie/work"
db_path = "/var/lib/archie/archie.db"
work_dir = "~/.local/share/archie/work"
db_path = "~/.local/share/archie/archie.db"
[forge]
type = "gitea"
@@ -46,8 +45,9 @@ parked = "agent:parked"
mode = "nats"
[nats]
# "nats" is the compose service name, resolved on the stack's own network.
url = "nats://nats:4222"
# The pinned Compose-network gateway is reachable from both the host daemon
# and the task containers it launches on archie-core_default.
url = "nats://172.19.0.1:4222"
[containers]
enabled = true
@@ -61,8 +61,7 @@ max_uptime = "60m"
pull_policy = "missing"
[web]
# 0.0.0.0 so the dashboard is reachable through the published port.
listen = "0.0.0.0:8484"
listen = "127.0.0.1:8484"
[models]
triage = "deepseek/deepseek-v4-pro"
@@ -98,9 +97,8 @@ gate = [
["go", "test", "./...", "-count=1"],
]
# Every env var named here must appear BOTH in the host .env and in
# docker-compose.yml's `environment:` passthrough list -- a missing
# passthrough silently yields an empty value.
# Every env var named here must be present in the environment of the host
# archied process, normally through its configured supervisor or launch shell.
[chat.telegram]
token_env = "TELEGRAM_BOT_TOKEN"
# Empty list denies everyone.
+3 -2
View File
@@ -102,5 +102,6 @@ docker compose pull agent
```
**Paths.** Under compose the daemon saw bind-mounted paths; on the host it sees
the real ones. In particular `db_path` must point at the database's actual
location, or the daemon starts against an empty one.
the real ones. In particular `db_path` is the state-path prefix from which the
daemon derives independent task and conversation SQLite files; it must point
at the intended host location, or the daemon starts against empty files.
-23
View File
@@ -1,23 +0,0 @@
<!DOCTYPE html>
<html lang="en-US" dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>404 | Archie</title>
<meta name="description" content="Not Found">
<meta name="generator" content="VitePress v1.6.4">
<link rel="preload stylesheet" href="/assets/style.C4BXn3EN.css" as="style">
<link rel="preload stylesheet" href="/vp-icons.css" as="style">
<script type="module" src="/assets/app.HIbJYLU1.js"></script>
<link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="icon" href="/favicon.svg">
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
</head>
<body>
<div id="app"></div>
<script>window.__VP_HASH_MAP__=JSON.parse("{\"architecture_agent-system.md\":\"Coj6mPZw\",\"architecture_configuration.md\":\"BsVGi7ja\",\"architecture_dependencies-and-contracts.md\":\"ByRODJZC\",\"architecture_generated-documentation.md\":\"qELen1k6\",\"architecture_identity.md\":\"CB0DkYo9\",\"architecture_index.md\":\"DJpk2YHf\",\"architecture_messaging-and-work-intake.md\":\"Q7MxXQDB\",\"architecture_migration-decisions.md\":\"oN2eGfag\",\"architecture_organisation.md\":\"mAPb3vCC\",\"architecture_package-review.md\":\"7BZCENBd\",\"architecture_plugins-and-extensions.md\":\"DmzsC2M0\",\"architecture_policy.md\":\"4L33IZiY\",\"architecture_safe-change-and-recovery.md\":\"CdYeF0XF\",\"archive_archie-core-architecture.md\":\"Bqg5-owD\",\"archive_archie-core-skills-prd-v2.md\":\"D3RVdXag\",\"archive_archie-core-skills-prd.md\":\"D1oUBHEN\",\"archive_decisions.md\":\"DkenJ6mD\",\"archive_design.md\":\"BwF1bH5l\",\"archive_prds_multi-agent-collaboration.md\":\"zqWXF3O0\",\"archive_prds_typescript-plugin-engine.md\":\"DBR1GKuy\",\"archive_prds_yaegi-plugin-system.md\":\"V36uzfZI\",\"index.md\":\"BdS51Ijr\",\"prds_01-project-management.md\":\"DEpuIAgg\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Archie\",\"description\":\"Documentation for the Archie personal agent platform.\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/favicon.svg\",\"nav\":[{\"text\":\"Architecture\",\"link\":\"/architecture/\"}],\"sidebar\":{\"/architecture/\":[{\"text\":\"Architecture\",\"items\":[{\"text\":\"Overview\",\"link\":\"/architecture/\"},{\"text\":\"Repository Organisation\",\"link\":\"/architecture/organisation\"},{\"text\":\"Dependencies and Contracts\",\"link\":\"/architecture/dependencies-and-contracts\"},{\"text\":\"Agent System\",\"link\":\"/architecture/agent-system\"},{\"text\":\"Configuration\",\"link\":\"/architecture/configuration\"},{\"text\":\"Identity\",\"link\":\"/architecture/identity\"},{\"text\":\"Messaging and Work Intake\",\"link\":\"/architecture/messaging-and-work-intake\"},{\"text\":\"Plugins and Extensions\",\"link\":\"/architecture/plugins-and-extensions\"},{\"text\":\"Policy System\",\"link\":\"/architecture/policy\"},{\"text\":\"Safe Change and Recovery\",\"link\":\"/architecture/safe-change-and-recovery\"},{\"text\":\"Generated Documentation\",\"link\":\"/architecture/generated-documentation\"},{\"text\":\"Domain and Feature Review Procedure\",\"link\":\"/architecture/package-review\"},{\"text\":\"Migration Decisions\",\"link\":\"/architecture/migration-decisions\"}]}]},\"search\":{\"provider\":\"local\"},\"footer\":{\"message\":\"Built with VitePress.\",\"copyright\":\"Archie\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
</body>
</html>
-35
View File
@@ -1,35 +0,0 @@
<!DOCTYPE html>
<html lang="en-US" dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Agent System | Archie</title>
<meta name="description" content="Documentation for the Archie personal agent platform.">
<meta name="generator" content="VitePress v1.6.4">
<link rel="preload stylesheet" href="/assets/style.C4BXn3EN.css" as="style">
<link rel="preload stylesheet" href="/vp-icons.css" as="style">
<script type="module" src="/assets/app.HIbJYLU1.js"></script>
<link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="modulepreload" href="/assets/chunks/theme.B97NJxv0.js">
<link rel="modulepreload" href="/assets/chunks/framework.BWuWLRhz.js">
<link rel="modulepreload" href="/assets/architecture_agent-system.md.Coj6mPZw.lean.js">
<link rel="icon" href="/favicon.svg">
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
</head>
<body>
<div id="app"><div class="Layout" data-v-cb931ff4><!--[--><!--]--><!--[--><span tabindex="-1" data-v-8ae66126></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-8ae66126>Skip to content</a><!--]--><!----><header class="VPNav" data-v-cb931ff4 data-v-a1925027><div class="VPNavBar" data-v-a1925027 data-v-2840085c><div class="wrapper" data-v-2840085c><div class="container" data-v-2840085c><div class="title" data-v-2840085c><div class="VPNavBarTitle has-sidebar" data-v-2840085c data-v-e7a29354><a class="title" href="/" data-v-e7a29354><!--[--><!--]--><!--[--><img class="VPImage logo" src="/favicon.svg" alt data-v-eec9b196><!--]--><span data-v-e7a29354>Archie</span><!--[--><!--]--></a></div></div><div class="content" data-v-2840085c><div class="content-body" data-v-2840085c><!--[--><!--]--><div class="VPNavBarSearch search" data-v-2840085c><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-2840085c data-v-ded89948><span id="main-nav-aria-label" class="visually-hidden" data-v-ded89948> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/architecture/" tabindex="0" data-v-ded89948 data-v-0a9a3d21><!--[--><span data-v-0a9a3d21>Architecture</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-2840085c data-v-4b074154><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-4b074154 data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-2840085c data-v-6ca47e2f data-v-b980f1c3><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-b980f1c3><span class="vpi-more-horizontal icon" data-v-b980f1c3></span></button><div class="menu" data-v-b980f1c3><div class="VPMenu" data-v-b980f1c3 data-v-a1767133><!----><!--[--><!--[--><!----><div class="group" data-v-6ca47e2f><div class="item appearance" data-v-6ca47e2f><p class="label" data-v-6ca47e2f>Appearance</p><div class="appearance-action" data-v-6ca47e2f><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-6ca47e2f data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-2840085c data-v-3597ebf2><span class="container" data-v-3597ebf2><span class="top" data-v-3597ebf2></span><span class="middle" data-v-3597ebf2></span><span class="bottom" data-v-3597ebf2></span></span></button></div></div></div></div><div class="divider" data-v-2840085c><div class="divider-line" data-v-2840085c></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-cb931ff4 data-v-c17e40bf><div class="container" data-v-c17e40bf><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-c17e40bf><span class="vpi-align-left menu-icon" data-v-c17e40bf></span><span class="menu-text" data-v-c17e40bf>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-c17e40bf data-v-88669269><button data-v-88669269>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-cb931ff4 data-v-f5090d1d><div class="curtain" data-v-f5090d1d></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-f5090d1d><span class="visually-hidden" id="sidebar-aria-label" data-v-f5090d1d> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-049afe89><section class="VPSidebarItem level-0 has-active" data-v-049afe89 data-v-ce191e9a><div class="item" role="button" tabindex="0" data-v-ce191e9a><div class="indicator" data-v-ce191e9a></div><h2 class="text" data-v-ce191e9a>Architecture</h2><!----></div><div class="items" data-v-ce191e9a><!--[--><div class="VPSidebarItem level-1 is-link" data-v-ce191e9a><div class="item" data-v-ce191e9a><div class="indicator" data-v-ce191e9a></div><a class="VPLink link link" href="/architecture/" data-v-ce19Line truncated
<span class="line"><span>internal/domain/workflow</span></span></code></pre></div><p>The Agent domain owns persistent assistants, their specialisation, instructions, model-independent continuity, capability context, and associations with identity and memory.</p><p>The Workflow domain owns reusable, user- or Agent-defined behaviour and every durable execution of that behaviour. An Agent may invoke or define a Workflow, but the Workflow is not part of the Agent aggregate and does not require a conversational Agent interaction to execute.</p><h2 id="canonical-workflow-model" tabindex="-1">Canonical workflow model <a class="header-anchor" href="#canonical-workflow-model" aria-label="Permalink to &quot;Canonical workflow model&quot;">​</a></h2><p>The Workflow feature uses these canonical terms:</p><ul><li><strong>Workflow</strong>: a reusable, versioned definition of how an agent behaves and performs a kind of work.</li><li><strong>WorkflowExecution</strong>: one durable execution of a specific Workflow version.</li><li><strong>WorkflowStep</strong>: one defined operation in a Workflow.</li><li><strong>StepExecution</strong>: the recorded execution and outcome of one WorkflowStep.</li><li><strong>Attempt</strong>: a retry of the same WorkflowExecution, not a new execution.</li></ul><p>A Workflow MAY structure any repeatable agent behaviour, including personal assistance and scheduled routines. For example, a morning email review may combine a schedule event, message retrieval tool, LLM classification and summarisation, and delivery of the resulting rundown. Workflow is therefore not restricted to forge work, source changes, or requests submitted by a user at execution time.</p><p>Workflows are extensible through Workflow-owned plugins. The Workflow domain defines the typed plugin registration, definition, validation, versioning, and execution contracts. Users and Agents may define reusable Workflows through those contracts.</p><p>The generic plugin contract remains metadata-only. It MUST NOT own Workflow semantics or replace the Workflow registry with generic hooks.</p><p><code>Workflow</code> and <code>WorkflowExecution</code> are the names used in architecture, generated reference, configuration, commands, events, and external contracts. The implementation MAY use package qualification to remain concise:</p><div class="language-go vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">go</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">workflow.Definition</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">workflow.Execution</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">workflow.Step</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">workflow.StepExecution</span></span></code></pre></div><p>The unqualified name <code>Execution</code> MUST NOT be used in cross-domain contracts or documentation because it is ambiguous among workflow, tool, command, policy, and service execution.</p><h2 id="current-workflow-execution-feature" tabindex="-1">Current workflow-execution feature <a class="header-anchor" href="#current-workflow-execution-feature" aria-label="Permalink to &quot;Current workflow-execution feature&quot;">​</a></h2><p>The current feature takes a channel request through agent execution and a durable outcome.</p><p>Current execution state includes source-message references, owning identity, repository, selected workflow and stage, agent output, branch and pull-request references, token and iteration counts, retry information, human-wait information, and failure details.</p><p>The current <code>store.Task</code> lifecycle uses:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>queued -&gt; running</span></span>
<span class="line"><span>running -&gt; waiting_human | pr_open | merged | parked | closed_wont_do</span></span>
<span class="line"><span>waiting_human -&gt; queued | closed_wont_do</span></span>
<span class="line"><span>parked -&gt; queued | dead</span></span>
<span class="line"><span>pr_open -&gt; merged | rejected</span></span>
<span class="line"><span>running after crash -&gt; queued</span></span></code></pre></div><p>Workflows select and sequence deterministic and agent-run stages. Implement, TDD, feasibility, and bootstrap are current Workflow definitions. WorkflowExecutions may run in-process or be handed wholesale to <code>archie-agent</code>.</p><h2 id="current-workflow-feature-placement" tabindex="-1">Current workflow-feature placement <a class="header-anchor" href="#current-workflow-feature-placement" aria-label="Permalink to &quot;Current workflow-feature placement&quot;">​</a></h2><p>The behaviour is divided across technical packages:</p><ul><li><code>internal/store</code> defines the current <code>Task</code> execution record and status strings and persists mutable state and transition history.</li><li><code>internal/daemon</code> discovers, claims, schedules, retries, recovers, processes, waits for human input, and reconciles pull requests.</li><li><code>internal/workflow</code> routes work, executes stages, mutates tasks, applies outcomes, parks failures, and performs forge/worktree operations.</li><li><code>internal/agentexec</code> defines and runs individual autonomous-stage protocols.</li><li><code>internal/taskrun</code> hands a complete WorkflowExecution to a container worker.</li><li><code>internal/gate</code> and repository configuration define execution constraints.</li><li><code>internal/gateway</code> duplicates task status strings and applies task-control rules.</li><li>forge, worktree, NATS, SQLite, containers, and agent runtimes are concrete dependencies mixed into orchestration.</li></ul><h2 id="current-task-meanings-and-required-replacements" tabindex="-1">Current <code>task</code> meanings and required replacements <a class="header-anchor" href="#current-task-meanings-and-required-replacements" aria-label="Permalink to &quot;Current `task` meanings and required replacements&quot;">​</a></h2><p>The existing code uses <code>task</code> for unrelated concepts. Migration MUST resolve each meaning deliberately; a global text replacement is prohibited.</p><table tabindex="0"><thead><tr><th>Current meaning</th><th>Representative locations</th><th>Target concept</th><th>Requirements</th></tr></thead><tbody><tr><td>Forge issue or external task</td><td><code>internal/forge</code>, daemon polling</td><td>Channel message</td><td>Preserve the channel&#39;s native reference and payload. Translate it into an Agent System request without importing forge or issue semantics into Workflow.</td></tr><tr><td>Jira issue or other external work item</td><td>Messaging infrastructure adapter</td><td>Channel message or external artifact</td><td>The external system retains its own vocabulary inside its integration. Its record may lead to an accepted work request but is not a Workflow or WorkflowExecution.</td></tr><tr><td>Persisted <code>store.Task</code> row/document</td><td><code>internal/store</code>, <code>internal/nell</code></td><td>WorkflowExecution</td><td>Own identity, Workflow ID and version, lifecycle, source-message reference, outputs, attempts, and outcome. Persistence implements the Agent System repository contract.</td></tr><tr><td>Task status and transition history</td><td><code>store.Status*</code>, <code>transitions</code>, Nell documents</td><td>WorkflowExecution lifecycle and domain events</td><td>Enforce legal transitions atomically. Domain events and state changes cannot diverge. Remove duplicated status strings from consumers.</td></tr><tr><td>Claimed or queued task</td><td><code>ClaimNext</code>, <code>ClaimByIssue</code>, <code>RecoverStale</code></td><td>Scheduled WorkflowExecution</td><td>Claim by WorkflowExecution ID and expected version/state. Crash recovery and leases must not silently create a new execution.</td></tr><tr><td><code>workflow.TaskContext</code></td><td><code>internal/workflow</code></td><td>WorkflowExecution context</td><td>Replace the mutable service bag with execution state plus narrow step-required contracts. Complete application configuration and unrelated services are forbidden.</td></tr><tr><td><code>taskrun.Request</code> and <code>taskrun.Response</code></td><td><code>internal/taskrun</code>, <code>cmd/archie-agent</code></td><td>WorkflowExecution handoff</td><td>This is the versioned worker contract for executing a WorkflowExecution. It carries domain-owned execution data, not store rows or global configuration DTOs.</td></tr><tr><td>Per-stage <code>agentexec.Request.TaskID</code></td><td><code>internal/agentexec</code></td><td>WorkflowExecutionID correlation</td><td>An agent invocation is a bounded WorkflowStep execution. Correlate request/result with WorkflowExecutionID, StepExecutionID, attempt, and protocol version.</td></tr><tr><td>NATS <code>TaskMessage</code> and <code>archie.task.*</code></td><td><code>internal/nats</code></td><td>Channel request or WorkflowExecution transport</td><td>Discovery messages and execution dispatch are different contracts and subjects.Line truncated
<script>window.__VP_HASH_MAP__=JSON.parse("{\"architecture_agent-system.md\":\"Coj6mPZw\",\"architecture_configuration.md\":\"BsVGi7ja\",\"architecture_dependencies-and-contracts.md\":\"ByRODJZC\",\"architecture_generated-documentation.md\":\"qELen1k6\",\"architecture_identity.md\":\"CB0DkYo9\",\"architecture_index.md\":\"DJpk2YHf\",\"architecture_messaging-and-work-intake.md\":\"Q7MxXQDB\",\"architecture_migration-decisions.md\":\"oN2eGfag\",\"architecture_organisation.md\":\"mAPb3vCC\",\"architecture_package-review.md\":\"7BZCENBd\",\"architecture_plugins-and-extensions.md\":\"DmzsC2M0\",\"architecture_policy.md\":\"4L33IZiY\",\"architecture_safe-change-and-recovery.md\":\"CdYeF0XF\",\"archive_archie-core-architecture.md\":\"Bqg5-owD\",\"archive_archie-core-skills-prd-v2.md\":\"D3RVdXag\",\"archive_archie-core-skills-prd.md\":\"D1oUBHEN\",\"archive_decisions.md\":\"DkenJ6mD\",\"archive_design.md\":\"BwF1bH5l\",\"archive_prds_multi-agent-collaboration.md\":\"zqWXF3O0\",\"archive_prds_typescript-plugin-engine.md\":\"DBR1GKuy\",\"archive_prds_yaegi-plugin-system.md\":\"V36uzfZI\",\"index.md\":\"BdS51Ijr\",\"prds_01-project-management.md\":\"DEpuIAgg\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Archie\",\"description\":\"Documentation for the Archie personal agent platform.\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/favicon.svg\",\"nav\":[{\"text\":\"Architecture\",\"link\":\"/architecture/\"}],\"sidebar\":{\"/architecture/\":[{\"text\":\"Architecture\",\"items\":[{\"text\":\"Overview\",\"link\":\"/architecture/\"},{\"text\":\"Repository Organisation\",\"link\":\"/architecture/organisation\"},{\"text\":\"Dependencies and Contracts\",\"link\":\"/architecture/dependencies-and-contracts\"},{\"text\":\"Agent System\",\"link\":\"/architecture/agent-system\"},{\"text\":\"Configuration\",\"link\":\"/architecture/configuration\"},{\"text\":\"Identity\",\"link\":\"/architecture/identity\"},{\"text\":\"Messaging and Work Intake\",\"link\":\"/architecture/messaging-and-work-intake\"},{\"text\":\"Plugins and Extensions\",\"link\":\"/architecture/plugins-and-extensions\"},{\"text\":\"Policy System\",\"link\":\"/architecture/policy\"},{\"text\":\"Safe Change and Recovery\",\"link\":\"/architecture/safe-change-and-recovery\"},{\"text\":\"Generated Documentation\",\"link\":\"/architecture/generated-documentation\"},{\"text\":\"Domain and Feature Review Procedure\",\"link\":\"/architecture/package-review\"},{\"text\":\"Migration Decisions\",\"link\":\"/architecture/migration-decisions\"}]}]},\"search\":{\"provider\":\"local\"},\"footer\":{\"message\":\"Built with VitePress.\",\"copyright\":\"Archie\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
</body>
</html>
-26
View File
@@ -1,26 +0,0 @@
<!DOCTYPE html>
<html lang="en-US" dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Configuration | Archie</title>
<meta name="description" content="Documentation for the Archie personal agent platform.">
<meta name="generator" content="VitePress v1.6.4">
<link rel="preload stylesheet" href="/assets/style.C4BXn3EN.css" as="style">
<link rel="preload stylesheet" href="/vp-icons.css" as="style">
<script type="module" src="/assets/app.HIbJYLU1.js"></script>
<link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="modulepreload" href="/assets/chunks/theme.B97NJxv0.js">
<link rel="modulepreload" href="/assets/chunks/framework.BWuWLRhz.js">
<link rel="modulepreload" href="/assets/architecture_configuration.md.BsVGi7ja.lean.js">
<link rel="icon" href="/favicon.svg">
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
</head>
<body>
<div id="app"><div class="Layout" data-v-cb931ff4><!--[--><!--]--><!--[--><span tabindex="-1" data-v-8ae66126></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-8ae66126>Skip to content</a><!--]--><!----><header class="VPNav" data-v-cb931ff4 data-v-a1925027><div class="VPNavBar" data-v-a1925027 data-v-2840085c><div class="wrapper" data-v-2840085c><div class="container" data-v-2840085c><div class="title" data-v-2840085c><div class="VPNavBarTitle has-sidebar" data-v-2840085c data-v-e7a29354><a class="title" href="/" data-v-e7a29354><!--[--><!--]--><!--[--><img class="VPImage logo" src="/favicon.svg" alt data-v-eec9b196><!--]--><span data-v-e7a29354>Archie</span><!--[--><!--]--></a></div></div><div class="content" data-v-2840085c><div class="content-body" data-v-2840085c><!--[--><!--]--><div class="VPNavBarSearch search" data-v-2840085c><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-2840085c data-v-ded89948><span id="main-nav-aria-label" class="visually-hidden" data-v-ded89948> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/architecture/" tabindex="0" data-v-ded89948 data-v-0a9a3d21><!--[--><span data-v-0a9a3d21>Architecture</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-2840085c data-v-4b074154><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-4b074154 data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-2840085c data-v-6ca47e2f data-v-b980f1c3><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-b980f1c3><span class="vpi-more-horizontal icon" data-v-b980f1c3></span></button><div class="menu" data-v-b980f1c3><div class="VPMenu" data-v-b980f1c3 data-v-a1767133><!----><!--[--><!--[--><!----><div class="group" data-v-6ca47e2f><div class="item appearance" data-v-6ca47e2f><p class="label" data-v-6ca47e2f>Appearance</p><div class="appearance-action" data-v-6ca47e2f><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-6ca47e2f data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-2840085c data-v-3597ebf2><span class="container" data-v-3597ebf2><span class="top" data-v-3597ebf2></span><span class="middle" data-v-3597ebf2></span><span class="bottom" data-v-3597ebf2></span></span></button></div></div></div></div><div class="divider" data-v-2840085c><div class="divider-line" data-v-2840085c></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-cb931ff4 data-v-c17e40bf><div class="container" data-v-c17e40bf><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-c17e40bf><span class="vpi-align-left menu-icon" data-v-c17e40bf></span><span class="menu-text" data-v-c17e40bf>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-c17e40bf data-v-88669269><button data-v-88669269>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-cb931ff4 data-v-f5090d1d><div class="curtain" data-v-f5090d1d></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-f5090d1d><span class="visually-hidden" id="sidebar-aria-label" data-v-f5090d1d> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-049afe89><section class="VPSidebarItem level-0 has-active" data-v-049afe89 data-v-ce191e9a><div class="item" role="button" tabindex="0" data-v-ce191e9a><div class="indicator" data-v-ce191e9a></div><h2 class="text" data-v-ce191e9a>Architecture</h2><!----></div><div class="items" data-v-ce191e9a><!--[--><div class="VPSidebarItem level-1 is-link" data-v-ce191e9a><div class="item" data-v-ce191e9a><div class="indicator" data-v-ce191e9a></div><a class="VPLink link link" href="/architecture/" data-v-ce19Line truncated
<script>window.__VP_HASH_MAP__=JSON.parse("{\"architecture_agent-system.md\":\"Coj6mPZw\",\"architecture_configuration.md\":\"BsVGi7ja\",\"architecture_dependencies-and-contracts.md\":\"ByRODJZC\",\"architecture_generated-documentation.md\":\"qELen1k6\",\"architecture_identity.md\":\"CB0DkYo9\",\"architecture_index.md\":\"DJpk2YHf\",\"architecture_messaging-and-work-intake.md\":\"Q7MxXQDB\",\"architecture_migration-decisions.md\":\"oN2eGfag\",\"architecture_organisation.md\":\"mAPb3vCC\",\"architecture_package-review.md\":\"7BZCENBd\",\"architecture_plugins-and-extensions.md\":\"DmzsC2M0\",\"architecture_policy.md\":\"4L33IZiY\",\"architecture_safe-change-and-recovery.md\":\"CdYeF0XF\",\"archive_archie-core-architecture.md\":\"Bqg5-owD\",\"archive_archie-core-skills-prd-v2.md\":\"D3RVdXag\",\"archive_archie-core-skills-prd.md\":\"D1oUBHEN\",\"archive_decisions.md\":\"DkenJ6mD\",\"archive_design.md\":\"BwF1bH5l\",\"archive_prds_multi-agent-collaboration.md\":\"zqWXF3O0\",\"archive_prds_typescript-plugin-engine.md\":\"DBR1GKuy\",\"archive_prds_yaegi-plugin-system.md\":\"V36uzfZI\",\"index.md\":\"BdS51Ijr\",\"prds_01-project-management.md\":\"DEpuIAgg\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Archie\",\"description\":\"Documentation for the Archie personal agent platform.\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/favicon.svg\",\"nav\":[{\"text\":\"Architecture\",\"link\":\"/architecture/\"}],\"sidebar\":{\"/architecture/\":[{\"text\":\"Architecture\",\"items\":[{\"text\":\"Overview\",\"link\":\"/architecture/\"},{\"text\":\"Repository Organisation\",\"link\":\"/architecture/organisation\"},{\"text\":\"Dependencies and Contracts\",\"link\":\"/architecture/dependencies-and-contracts\"},{\"text\":\"Agent System\",\"link\":\"/architecture/agent-system\"},{\"text\":\"Configuration\",\"link\":\"/architecture/configuration\"},{\"text\":\"Identity\",\"link\":\"/architecture/identity\"},{\"text\":\"Messaging and Work Intake\",\"link\":\"/architecture/messaging-and-work-intake\"},{\"text\":\"Plugins and Extensions\",\"link\":\"/architecture/plugins-and-extensions\"},{\"text\":\"Policy System\",\"link\":\"/architecture/policy\"},{\"text\":\"Safe Change and Recovery\",\"link\":\"/architecture/safe-change-and-recovery\"},{\"text\":\"Generated Documentation\",\"link\":\"/architecture/generated-documentation\"},{\"text\":\"Domain and Feature Review Procedure\",\"link\":\"/architecture/package-review\"},{\"text\":\"Migration Decisions\",\"link\":\"/architecture/migration-decisions\"}]}]},\"search\":{\"provider\":\"local\"},\"footer\":{\"message\":\"Built with VitePress.\",\"copyright\":\"Archie\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
</body>
</html>
@@ -1,29 +0,0 @@
<!DOCTYPE html>
<html lang="en-US" dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Dependencies and Contracts | Archie</title>
<meta name="description" content="Documentation for the Archie personal agent platform.">
<meta name="generator" content="VitePress v1.6.4">
<link rel="preload stylesheet" href="/assets/style.C4BXn3EN.css" as="style">
<link rel="preload stylesheet" href="/vp-icons.css" as="style">
<script type="module" src="/assets/app.HIbJYLU1.js"></script>
<link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="modulepreload" href="/assets/chunks/theme.B97NJxv0.js">
<link rel="modulepreload" href="/assets/chunks/framework.BWuWLRhz.js">
<link rel="modulepreload" href="/assets/architecture_dependencies-and-contracts.md.ByRODJZC.lean.js">
<link rel="icon" href="/favicon.svg">
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
</head>
<body>
<div id="app"><div class="Layout" data-v-cb931ff4><!--[--><!--]--><!--[--><span tabindex="-1" data-v-8ae66126></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-8ae66126>Skip to content</a><!--]--><!----><header class="VPNav" data-v-cb931ff4 data-v-a1925027><div class="VPNavBar" data-v-a1925027 data-v-2840085c><div class="wrapper" data-v-2840085c><div class="container" data-v-2840085c><div class="title" data-v-2840085c><div class="VPNavBarTitle has-sidebar" data-v-2840085c data-v-e7a29354><a class="title" href="/" data-v-e7a29354><!--[--><!--]--><!--[--><img class="VPImage logo" src="/favicon.svg" alt data-v-eec9b196><!--]--><span data-v-e7a29354>Archie</span><!--[--><!--]--></a></div></div><div class="content" data-v-2840085c><div class="content-body" data-v-2840085c><!--[--><!--]--><div class="VPNavBarSearch search" data-v-2840085c><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-2840085c data-v-ded89948><span id="main-nav-aria-label" class="visually-hidden" data-v-ded89948> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/architecture/" tabindex="0" data-v-ded89948 data-v-0a9a3d21><!--[--><span data-v-0a9a3d21>Architecture</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-2840085c data-v-4b074154><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-4b074154 data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-2840085c data-v-6ca47e2f data-v-b980f1c3><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-b980f1c3><span class="vpi-more-horizontal icon" data-v-b980f1c3></span></button><div class="menu" data-v-b980f1c3><div class="VPMenu" data-v-b980f1c3 data-v-a1767133><!----><!--[--><!--[--><!----><div class="group" data-v-6ca47e2f><div class="item appearance" data-v-6ca47e2f><p class="label" data-v-6ca47e2f>Appearance</p><div class="appearance-action" data-v-6ca47e2f><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-6ca47e2f data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-2840085c data-v-3597ebf2><span class="container" data-v-3597ebf2><span class="top" data-v-3597ebf2></span><span class="middle" data-v-3597ebf2></span><span class="bottom" data-v-3597ebf2></span></span></button></div></div></div></div><div class="divider" data-v-2840085c><div class="divider-line" data-v-2840085c></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-cb931ff4 data-v-c17e40bf><div class="container" data-v-c17e40bf><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-c17e40bf><span class="vpi-align-left menu-icon" data-v-c17e40bf></span><span class="menu-text" data-v-c17e40bf>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-c17e40bf data-v-88669269><button data-v-88669269>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-cb931ff4 data-v-f5090d1d><div class="curtain" data-v-f5090d1d></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-f5090d1d><span class="visually-hidden" id="sidebar-aria-label" data-v-f5090d1d> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-049afe89><section class="VPSidebarItem level-0 has-active" data-v-049afe89 data-v-ce191e9a><div class="item" role="button" tabindex="0" data-v-ce191e9a><div class="indicator" data-v-ce191e9a></div><h2 class="text" data-v-ce191e9a>Architecture</h2><!----></div><div class="items" data-v-ce191e9a><!--[--><div class="VPSidebarItem level-1 is-link" data-v-ce191e9a><div class="item" data-v-ce191e9a><div class="indicator" data-v-ce191e9a></div><a class="VPLink link link" href="/architecture/" data-v-ce19Line truncated
<span class="line"><span> ^</span></span>
<span class="line"><span> |</span></span>
<span class="line"><span> application composition</span></span></code></pre></div><p>The following rules are strict:</p><ol><li>Domains MUST NOT import <code>internal/infrastructure</code>.</li><li>A domain defines the smallest interfaces required to perform its work.</li><li>Infrastructure implements those interfaces and translates external representations at the boundary.</li><li>Only application composition chooses concrete implementations.</li><li>A domain MUST NOT manipulate another domain&#39;s state or call its internal services.</li><li>Cross-domain work uses an explicitly designed command, event, or approved shared contract.</li><li>Implementation difficulty is not permission to violate a boundary.</li></ol><p>Broker messages, database rows, SDK response types, and configuration DTOs MUST NOT leak into domain models.</p><h2 id="commands-and-events" tabindex="-1">Commands and events <a class="header-anchor" href="#commands-and-events" aria-label="Permalink to &quot;Commands and events&quot;">​</a></h2><ul><li>An event records something that happened and is owned by its publishing domain.</li><li>A command requests an action and is owned by the domain expected to handle it.</li><li>Consumers do not redefine an event&#39;s meaning.</li><li>Senders obey the receiving domain&#39;s command contract.</li><li>There is no generic package containing unrelated application messages.</li></ul><h2 id="event-bus" tabindex="-1">Event bus <a class="header-anchor" href="#event-bus" aria-label="Permalink to &quot;Event bus&quot;">​</a></h2><p><code>internal/eventbus</code> is an approved shared application contract. It defines only the messaging behaviour Archie requires, including publication, subscription, delivery outcomes, and required lifecycle semantics.</p><p>It MUST remain broker-neutral. NATS subjects, JetStream configuration, consumer groups, acknowledgements, reconnection, and serialization belong under <code>internal/infrastructure/eventbus/nats</code> unless Archie explicitly requires a semantic guarantee in the shared contract.</p><p>Message schemas stay with their owning domains. The event bus transports messages; it does not own their meaning.</p><h2 id="wire-contracts-and-generation" tabindex="-1">Wire contracts and generation <a class="header-anchor" href="#wire-contracts-and-generation" aria-label="Permalink to &quot;Wire contracts and generation&quot;">​</a></h2><p>Canonical worker and service wire contracts and their authoritative generation inputs are owned by the domain or capability that defines their meaning. They MUST NOT be centralized in <code>internal/infrastructure/spec</code> or another generic schema package.</p><p>Infrastructure owns:</p><ul><li>generic contract-generation machinery;</li><li>transport-specific adapters and generated implementations;</li><li>RPC, REST, NATS, and other external encoding and delivery concerns.</li></ul><p>For example, agent-worker requests and results belong to task execution. Subprocess, NATS, or HTTP representations are infrastructure implementations of that contract. The same rule applies independently to forge, persistence, workspace, and other service contracts.</p></div></div></main><footer class="VPDocFooter" data-v-81f89caf data-v-1e23d7de><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-1e23d7de><span class="visually-hidden" id="doc-footer-aria-label" data-v-1e23d7de>Pager</span><div class="pager" data-v-1e23d7de><a class="VPLink link pager-link prev" href="/architecture/organisation" data-v-1e23d7de><!--[--><span class="desc" data-v-1e23d7de>Previous page</span><span class="title" data-v-1e23d7de>Repository Organisation</span><!--]--></a></div><div class="pager" data-v-1e23d7de><a class="VPLink link pager-link next" href="/architecture/agent-system" data-v-1e23d7de><!--[--><span class="desc" data-v-1e23d7de>Next page</span><span class="title" data-v-1e23d7de>Agent System</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><footer class="VPFooter has-sidebar" data-v-cb931ff4 data-v-c113a85a><div class="container" data-v-c113a85a><p class="message" data-v-c113a85a>Built with VitePress.</p><p class="copyright" data-v-c113a85a>Archie</p></div></footer><!--[--><!--]--></div></div>
<script>window.__VP_HASH_MAP__=JSON.parse("{\"architecture_agent-system.md\":\"Coj6mPZw\",\"architecture_configuration.md\":\"BsVGi7ja\",\"architecture_dependencies-and-contracts.md\":\"ByRODJZC\",\"architecture_generated-documentation.md\":\"qELen1k6\",\"architecture_identity.md\":\"CB0DkYo9\",\"architecture_index.md\":\"DJpk2YHf\",\"architecture_messaging-and-work-intake.md\":\"Q7MxXQDB\",\"architecture_migration-decisions.md\":\"oN2eGfag\",\"architecture_organisation.md\":\"mAPb3vCC\",\"architecture_package-review.md\":\"7BZCENBd\",\"architecture_plugins-and-extensions.md\":\"DmzsC2M0\",\"architecture_policy.md\":\"4L33IZiY\",\"architecture_safe-change-and-recovery.md\":\"CdYeF0XF\",\"archive_archie-core-architecture.md\":\"Bqg5-owD\",\"archive_archie-core-skills-prd-v2.md\":\"D3RVdXag\",\"archive_archie-core-skills-prd.md\":\"D1oUBHEN\",\"archive_decisions.md\":\"DkenJ6mD\",\"archive_design.md\":\"BwF1bH5l\",\"archive_prds_multi-agent-collaboration.md\":\"zqWXF3O0\",\"archive_prds_typescript-plugin-engine.md\":\"DBR1GKuy\",\"archive_prds_yaegi-plugin-system.md\":\"V36uzfZI\",\"index.md\":\"BdS51Ijr\",\"prds_01-project-management.md\":\"DEpuIAgg\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Archie\",\"description\":\"Documentation for the Archie personal agent platform.\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/favicon.svg\",\"nav\":[{\"text\":\"Architecture\",\"link\":\"/architecture/\"}],\"sidebar\":{\"/architecture/\":[{\"text\":\"Architecture\",\"items\":[{\"text\":\"Overview\",\"link\":\"/architecture/\"},{\"text\":\"Repository Organisation\",\"link\":\"/architecture/organisation\"},{\"text\":\"Dependencies and Contracts\",\"link\":\"/architecture/dependencies-and-contracts\"},{\"text\":\"Agent System\",\"link\":\"/architecture/agent-system\"},{\"text\":\"Configuration\",\"link\":\"/architecture/configuration\"},{\"text\":\"Identity\",\"link\":\"/architecture/identity\"},{\"text\":\"Messaging and Work Intake\",\"link\":\"/architecture/messaging-and-work-intake\"},{\"text\":\"Plugins and Extensions\",\"link\":\"/architecture/plugins-and-extensions\"},{\"text\":\"Policy System\",\"link\":\"/architecture/policy\"},{\"text\":\"Safe Change and Recovery\",\"link\":\"/architecture/safe-change-and-recovery\"},{\"text\":\"Generated Documentation\",\"link\":\"/architecture/generated-documentation\"},{\"text\":\"Domain and Feature Review Procedure\",\"link\":\"/architecture/package-review\"},{\"text\":\"Migration Decisions\",\"link\":\"/architecture/migration-decisions\"}]}]},\"search\":{\"provider\":\"local\"},\"footer\":{\"message\":\"Built with VitePress.\",\"copyright\":\"Archie\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
</body>
</html>
@@ -1,84 +0,0 @@
<!DOCTYPE html>
<html lang="en-US" dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Generated Documentation and Documentation Site | Archie</title>
<meta name="description" content="Documentation for the Archie personal agent platform.">
<meta name="generator" content="VitePress v1.6.4">
<link rel="preload stylesheet" href="/assets/style.C4BXn3EN.css" as="style">
<link rel="preload stylesheet" href="/vp-icons.css" as="style">
<script type="module" src="/assets/app.HIbJYLU1.js"></script>
<link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="modulepreload" href="/assets/chunks/theme.B97NJxv0.js">
<link rel="modulepreload" href="/assets/chunks/framework.BWuWLRhz.js">
<link rel="modulepreload" href="/assets/architecture_generated-documentation.md.qELen1k6.lean.js">
<link rel="icon" href="/favicon.svg">
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
</head>
<body>
<div id="app"><div class="Layout" data-v-cb931ff4><!--[--><!--]--><!--[--><span tabindex="-1" data-v-8ae66126></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-8ae66126>Skip to content</a><!--]--><!----><header class="VPNav" data-v-cb931ff4 data-v-a1925027><div class="VPNavBar" data-v-a1925027 data-v-2840085c><div class="wrapper" data-v-2840085c><div class="container" data-v-2840085c><div class="title" data-v-2840085c><div class="VPNavBarTitle has-sidebar" data-v-2840085c data-v-e7a29354><a class="title" href="/" data-v-e7a29354><!--[--><!--]--><!--[--><img class="VPImage logo" src="/favicon.svg" alt data-v-eec9b196><!--]--><span data-v-e7a29354>Archie</span><!--[--><!--]--></a></div></div><div class="content" data-v-2840085c><div class="content-body" data-v-2840085c><!--[--><!--]--><div class="VPNavBarSearch search" data-v-2840085c><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-2840085c data-v-ded89948><span id="main-nav-aria-label" class="visually-hidden" data-v-ded89948> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/architecture/" tabindex="0" data-v-ded89948 data-v-0a9a3d21><!--[--><span data-v-0a9a3d21>Architecture</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-2840085c data-v-4b074154><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-4b074154 data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-2840085c data-v-6ca47e2f data-v-b980f1c3><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-b980f1c3><span class="vpi-more-horizontal icon" data-v-b980f1c3></span></button><div class="menu" data-v-b980f1c3><div class="VPMenu" data-v-b980f1c3 data-v-a1767133><!----><!--[--><!--[--><!----><div class="group" data-v-6ca47e2f><div class="item appearance" data-v-6ca47e2f><p class="label" data-v-6ca47e2f>Appearance</p><div class="appearance-action" data-v-6ca47e2f><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-6ca47e2f data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-2840085c data-v-3597ebf2><span class="container" data-v-3597ebf2><span class="top" data-v-3597ebf2></span><span class="middle" data-v-3597ebf2></span><span class="bottom" data-v-3597ebf2></span></span></button></div></div></div></div><div class="divider" data-v-2840085c><div class="divider-line" data-v-2840085c></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-cb931ff4 data-v-c17e40bf><div class="container" data-v-c17e40bf><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-c17e40bf><span class="vpi-align-left menu-icon" data-v-c17e40bf></span><span class="menu-text" data-v-c17e40bf>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-c17e40bf data-v-88669269><button data-v-88669269>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-cb931ff4 data-v-f5090d1d><div class="curtain" data-v-f5090d1d></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-f5090d1d><span class="visually-hidden" id="sidebar-aria-label" data-v-f5090d1d> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-049afe89><section class="VPSidebarItem level-0 has-active" data-v-049afe89 data-v-ce191e9a><div class="item" role="button" tabindex="0" data-v-ce191e9a><div class="indicator" data-v-ce191e9a></div><h2 class="text" data-v-ce191e9a>Architecture</h2><!----></div><div class="items" data-v-ce191e9a><!--[--><div class="VPSidebarItem level-1 is-link" data-v-ce191e9a><div class="item" data-v-ce191e9a><div class="indicator" data-v-ce191e9a></div><a class="VPLink link link" href="/architecture/" data-v-ce19Line truncated
<span class="line"><span>tools/</span></span>
<span class="line"><span> go.mod</span></span>
<span class="line"><span> go.sum</span></span>
<span class="line"><span> docsgen/</span></span>
<span class="line"><span> main.go</span></span>
<span class="line"><span>docs/</span></span>
<span class="line"><span> .vitepress/</span></span>
<span class="line"><span> public/</span></span>
<span class="line"><span> package.json</span></span>
<span class="line"><span> pnpm-lock.yaml</span></span>
<span class="line"><span> pnpm-workspace.yaml</span></span>
<span class="line"><span> *.md</span></span></code></pre></div><h3 id="vitepress-site" tabindex="-1">VitePress site <a class="header-anchor" href="#vitepress-site" aria-label="Permalink to &quot;VitePress site&quot;">​</a></h3><p>The <code>docs</code> site provides:</p><ul><li>VitePress 1.6.x with pnpm;</li><li>Markdown content at the site root;</li><li>repository-owned navigation and sidebar configuration;</li><li>local full-text search;</li><li>clean URLs and last-updated metadata;</li><li>build output under <code>.vitepress/dist</code>;</li><li>GitHub Pages-compatible static output;</li></ul><h3 id="github-pages-workflow" tabindex="-1">GitHub Pages workflow <a class="header-anchor" href="#github-pages-workflow" aria-label="Permalink to &quot;GitHub Pages workflow&quot;">​</a></h3><p>The workflow provides:</p><ul><li>full-history checkout for VitePress <code>lastUpdated</code>;</li><li>pinned pnpm major version;</li><li>Node setup and pnpm caching;</li><li>VitePress cache reuse;</li><li>frozen-lockfile installation;</li><li>static build, artifact upload, and Pages deployment;</li><li>serialized deployments without cancelling an in-progress publish.</li></ul><h2 id="single-source-of-truth" tabindex="-1">Single source of truth <a class="header-anchor" href="#single-source-of-truth" aria-label="Permalink to &quot;Single source of truth&quot;">​</a></h2><p>Every published capability has one authoritative machine-readable definition owned by its domain or application boundary. Generated documentation derives from those definitions.</p><p>Generated reference includes:</p><ul><li>domain commands and events;</li><li>Messages and typed message content;</li><li>Agent and Workflow contracts;</li><li>WorkflowSteps and Workflow plugin capability contracts;</li><li>policies and their typed inputs and outcomes;</li><li>tools and capabilities;</li><li>CLI commands, arguments, flags, defaults, and help;</li><li>runtime settings, types, defaults, validation, and secret metadata;</li><li>public worker and transport contracts;</li><li>indexes of registered functionality;</li><li>deprecation information.</li></ul><p>Handwritten documents contain:</p><ul><li>architecture decisions and rationale;</li><li>tutorials and operational guides;</li><li>examples and walkthroughs;</li><li>migration guidance;</li><li>conceptual explanations.</li></ul><p>Handwritten documents link to generated reference rather than copying authoritative tables.</p><h2 id="target-generation-architecture" tabindex="-1">Target generation architecture <a class="header-anchor" href="#target-generation-architecture" aria-label="Permalink to &quot;Target generation architecture&quot;">​</a></h2><p><code>tools/docsgen</code> is Archie&#39;s documentation extractor and normalizer. It produces structured documentation data and protocol specifications. It does not own page layout and MUST NOT generate Markdown pages or fragments.</p><p>The generator is divided internally into reusable stages:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>load registries and types</span></span>
<span class="line"><span> -&gt; normalize documentation model</span></span>
<span class="line"><span> -&gt; validate ownership and identifiers</span></span>
<span class="line"><span> -&gt; serialize data and protocol artifacts</span></span>
<span class="line"><span> -&gt; compare or write output</span></span></code></pre></div><p>The normalized documentation model prevents each output renderer from independently interpreting Go types. It contains stable documentation IDs, owners, names, descriptions, source references, versions, deprecations, fields, defaults, validation, secret classifications, and relationships.</p><p>Initial generator targets:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>docsgen data</span></span>
<span class="line"><span>docsgen asyncapi</span></span>
<span class="line"><span>docsgen all</span></span>
<span class="line"><span>docsgen check</span></span></code></pre></div><ul><li><code>data</code> writes the normalized JSON consumed by VitePress.</li><li><code>asyncapi</code> writes protocol schemas and envelopes.</li><li><code>all</code> generates every committed artifact.</li><li><code>check</code> generates into a temporary directory and fails on drift.</li></ul><p>The command may use subcommands or an equivalent explicit <code>--target</code> flag. It MUST retain one normalization and validation path.</p><h2 id="target-output" tabindex="-1">Target output <a class="header-anchor" href="#target-output" aria-label="Permalink to &quot;Target output&quot;">​</a></h2><p>During adaptation, <code>docs</code> remains the staging site. Generated outputs live in a visibly owned subtree:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>docs/</span></span>
<span class="line"><span> data/</span></span>
<span class="line"><span> generated/</span></span>
<span class="line"><span> catalog.json</span></span>
<span class="line"><span> contracts.json</span></span>
<span class="line"><span> cli.json</span></span>
<span class="line"><span> configuration.json</span></span>
<span class="line"><span> messaging.json</span></span>
<span class="line"><span> agents.json</span></span>
<span class="line"><span> workflows.json</span></span>
<span class="line"><span> policies.json</span></span>
<span class="line"><span> plugins.json</span></span>
<span class="line"><span> tools.json</span></span>
<span class="line"><span> public/</span></span>
<span class="line"><span> schemas/</span></span>
<span class="line"><span> asyncapi-header.yaml</span></span>
<span class="line"><span> archie.yaml</span></span>
<span class="line"><span> .vitepress/</span></span>
<span class="line"><span> config.mts</span></span>
<span class="line"><span> data/</span></span>
<span class="line"><span> reference.data.ts</span></span>
<span class="line"><span> theme/</span></span>
<span class="line"><span> components/</span></span>
<span class="line"><span> .tmp/</span></span></code></pre></div><p>All files under <code>data/generated/</code> and <code>public/schemas/</code> carry generated ownership metadata where their format permits it and MUST NOT be edited manually. <code>.tmp/</code> is generator-owned, ignored, and never committed.</p><p><code>catalog.json</code> is the deterministic machine-readable index used for:</p><ul><li>reference navigation and route inputs;</li><li>duplicate-ID and duplicate-route validation;</li><li>coverage checks;</li><li>source-to-data drift diagnostics;</li><li>future external consumers.</li></ul><p>VitePress loads these files at build time through a typed <code>.data.ts</code> loader. Pages and components import the loader&#39;s <code>data</code> export and render reference views. Archie uses a custom loader because the authoritative inputs are JSON; VitePress <code>createContentLoader</code> is reserved for Markdown content collections.</p><p>The final move from <code>docs/</code> to <code>docs/</code> occurs only after Archie content contains intentional Archie pages and the current architecture documents have an intentional destination. The staging name MUST NOT leak into public URLs.</p><h2 id="generation-steps" tabindex="-1">Generation steps <a class="header-anchor" href="#generation-steps" aria-label="Permalink to &quot;Generation steps&quot;">​</a></h2><h3 id="step-1-maintain-the-archie-tools-module" tabindex="-1">Step 1: maintain the Archie tools module <a class="header-anchor" href="#step-1-maintain-the-archie-tools-module" aria-label="Permalink to &quot;Step 1: maintain the Archie tools module&quot;">​</a></h3><p>Keep <code>tools/go.mod</code> isolated from the runtime module:</p><div class="language-go vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">go</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">module github.com</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">/</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">samcharles93</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">/</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">archie</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">core</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">/</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">tools</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">require github.com</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">/</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">samcharles93</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">/</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">archie</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">core v0.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">0.0</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">-</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">00010101000000</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">-</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">000000000000</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">replace github.com</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">/</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">samcharles93</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">/</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">archie</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">core </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ..</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">/</span></span></code></pre></div><p>Keep generator-only dependencies such as <code>invopop/jsonschema</code> and any future protocol-schema serializer in the nested tools module. They MUST NOT enter the root module.</p><p><code>docsgen</code> imports Archie-owned contracts and writes normalized Archie data and protocol artifacts.</p><h3 id="step-2-establish-authoritative-registries" tabindex="-1">Step 2: establish authoritative registries <a class="header-anchor" href="#step-2-establish-authoritative-registries" aria-label="Permalink to &quot;Step 2: establish authoritative registries&quot;">​</a></h3><p>The generator consumes domain-owned registries rather than scanning arbitrary packages for anything exported.</p><p>Each published definition supplies:</p><ul><li>stable documentation ID;</li><li>owning domain or boundary;</li><li>name and description;</li><li>version when versioned;</li><li>the Go type or declarative definition;</li><li>lifecycle and deprecation metadata;</li><li>source reference.</li></ul><p>Registries remain executable application definitions used by production code. A documentation-only duplicate registry is prohibited.</p><p>Where the migration has not yet created a final domain registry, the generator may use a narrow compatibility adapter over the current registry. That adapter has explicit deletion criteria.</p><p>The initial agent-execution and messaging schema set is such an adapter. It is deleted when those domains expose their production-owned documentation registries; adding another hardcoded type list to <code>docsgen</code> is prohibited.</p><h3 id="step-3-generate-asyncapi" tabindex="-1">Step 3: generate AsyncAPI <a class="header-anchor" href="#step-3-generate-asyncapi" aria-label="Permalink to &quot;Step 3: generate AsyncAPI&quot;">​</a></h3><p>Use Archie&#39;s messaging and worker wire registries as the authoritative inputs.</p><p>The static header continues to own:</p><ul><li>AsyncAPI version;</li><li>service and protocol description;</li><li>servers;</li><li>channels;</li><li>operations;</li><li>message envelope placement.</li></ul><p>The generator owns:</p><ul><li>component schemas;</li><li>discriminated concrete message lists;</li><li>generated envelopes;</li><li>rewritten schema references;</li><li>stable ordering.</li></ul><p>The generated protocol artifact becomes:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>docs/public/schemas/archie.yaml</span></span></code></pre></div><p>The final owner of each wire registry is the domain or capability defining its meaning. <code>docsgen</code> renders the contract; it does not own the message semantics.</p><h3 id="step-4-add-generated-documentation-data" tabindex="-1">Step 4: add generated documentation data <a class="header-anchor" href="#step-4-add-generated-documentation-data" aria-label="Permalink to &quot;Step 4: add generated documentation data&quot;">​</a></h3><p>Add extractors for the missing reference categories one vertical slice at a time.</p><p>Recommended implementation order:</p><ol><li>CLI commands and flags;</li><li>runtime configuration/settings;</li><li>Messaging commands, events, and message types;</li><li>Agent definitions and public commands;</li><li>Workflow definitions, WorkflowSteps, lifecycle, and plugin contracts;</li><li>policy definitions and typed outcomes;</li><li>tools and capability contracts;</li><li>worker and external wire contracts.</li></ol><p>Each category extractor contributes:</p><ul><li>stable IDs, owners, routes, and display ordering;</li><li>fields, types, defaults, and validation metadata;</li><li>source references;</li><li>version and deprecation information;</li><li>relationships to commands, events, policies, and contracts.</li></ul><p>The first vertical slice proves the normalized model and deterministic JSON serialization. Later categories reuse it rather than introducing category-specific ad hoc output formats.</p><h3 id="step-5-render-data-with-vitepress" tabindex="-1">Step 5: render data with VitePress <a class="header-anchor" href="#step-5-render-data-with-vitepress" aria-label="PeLine truncated
<span class="line"><span>task docs:check # go -C tools run ./docsgen check, then build VitePress</span></span>
<span class="line"><span>task docs:serve # generate, install if needed, then start VitePress dev</span></span>
<span class="line"><span>task docs:build # generate/check and create the production static site</span></span></code></pre></div><p>Commands use explicit paths:</p><div class="language-sh vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sh</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">go</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -C</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> tools</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./docsgen</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> all</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --repo-root</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ..</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">go</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -C</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> tools</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./docsgen</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> check</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --repo-root</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ..</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> docs</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> install</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --frozen-lockfile</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> docs</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> docs</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build</span></span></code></pre></div><p>The final command syntax must match the implemented CLI, but these task names and responsibilities are fixed.</p><p><code>task check</code> runs <code>docs:check</code>. Generated drift, invalid Markdown, dead links, or a failed VitePress build block completion.</p><h3 id="step-9-adapt-ci-and-pages-deployment" tabindex="-1">Step 9: adapt CI and Pages deployment <a class="header-anchor" href="#step-9-adapt-ci-and-pages-deployment" aria-label="Permalink to &quot;Step 9: adapt CI and Pages deployment&quot;">​</a></h3><p>The workflow watches:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>.github/workflows/docs.yml</span></span>
<span class="line"><span>docs/**</span></span>
<span class="line"><span>tools/go.mod</span></span>
<span class="line"><span>tools/go.sum</span></span>
<span class="line"><span>tools/docsgen/**</span></span>
<span class="line"><span>authoritative domain registry and type paths</span></span></code></pre></div><p>The build job:</p><ol><li>checks out full history;</li><li>installs the repository&#39;s Go version;</li><li>runs <code>docsgen check</code>;</li><li>installs the pinned pnpm version;</li><li>installs the configured Node version;</li><li>restores pnpm and VitePress caches;</li><li>installs dependencies with the frozen lockfile;</li><li>builds VitePress;</li><li>uploads <code>docs/.vitepress/dist</code>.</li></ol><p>The deploy job uses the required Pages permissions, environment, concurrency, and artifact deployment flow.</p><p>CI MUST check generated output; it MUST NOT regenerate and silently publish uncommitted differences.</p><h3 id="step-10-remove-non-source-artifacts-and-cut-over" tabindex="-1">Step 10: remove non-source artifacts and cut over <a class="header-anchor" href="#step-10-remove-non-source-artifacts-and-cut-over" aria-label="Permalink to &quot;Step 10: remove non-source artifacts and cut over&quot;">​</a></h3><p>Before treating the site as Archie documentation:</p><ul><li>keep <code>node_modules/</code> out of source control;</li><li>keep <code>.vitepress/dist/</code> out of source control;</li><li>ensure both paths are ignored;</li><li>remove Markdown, examples, specs, generated schemas, and assets that do not describe Archie;</li><li>adapt retained content and prove it against Archie code;</li><li>update <code>docs.go</code> and its tests to embed only intentional runtime documentation;</li><li>decide which current <code>docs/prds</code> remain published architecture pages and which remain repository-only planning documents;</li><li>rename <code>docs</code> to its final location;</li><li>update workflow, Taskfile, links, and embed paths atomically.</li></ul><p>Documents MUST describe Archie before they are published.</p><h2 id="hook-and-ci-policy" tabindex="-1">Hook and CI policy <a class="header-anchor" href="#hook-and-ci-policy" aria-label="Permalink to &quot;Hook and CI policy&quot;">​</a></h2><p>Generated documentation is committed.</p><p>The pre-commit hook:</p><ol><li>detects authoritative definition or generator changes;</li><li>runs <code>task docs:generate</code>;</li><li>runs <code>task docs:check</code>;</li><li>refuses the commit when generated changes are unstaged or validation fails.</li></ol><p>CI:</p><ol><li>runs <code>task docs:check</code> without modifying committed output;</li><li>builds the static site;</li><li>publishes only from the approved branch or release;</li><li>never treats generated data as handwritten source.</li></ol><p>A commit MUST NOT be created while generated documentation is stale.</p><h2 id="validation-requirements" tabindex="-1">Validation requirements <a class="header-anchor" href="#validation-requirements" aria-label="Permalink to &quot;Validation requirements&quot;">​</a></h2><p>Generator tests cover:</p><ul><li>stable ordering;</li><li>schema reference rewriting;</li><li><code>$defs</code> flattening;</li><li>duplicate IDs and routes;</li><li>registry coverage;</li><li>comments and descriptions;</li><li>secret redaction;</li><li>obsolete-file removal;</li><li>byte-identical repeated generation;</li><li>check-mode diagnostics.</li></ul><p>Site validation covers:</p><ul><li>frozen dependency installation;</li><li>VitePress production build;</li><li>dead internal links;</li><li>generated-data loader imports;</li><li>expected output routes;</li><li>absence of unrelated product names and URLs;</li><li>absence of committed build artifacts.</li></ul><p>The root module remains free of generator-only dependencies.</p><h2 id="completion-criteria" tabindex="-1">Completion criteria <a class="header-anchor" href="#completion-criteria" aria-label="Permalink to &quot;Completion criteria&quot;">​</a></h2><p>The documentation migration is complete when:</p><ul><li><code>tools</code> belongs to Archie and builds against the working tree;</li><li><code>docsgen</code> consumes Archie-owned registries and types;</li><li>AsyncAPI output describes Archie;</li><li>required reference categories are generated as committed deterministic data;</li><li><code>catalog.json</code> matches the generated definitions and rendered routes;</li><li>VitePress components and templates render the generated data;</li><li>two consecutive generations are byte-identical;</li><li><code>docsgen check</code> detects changed, missing, and obsolete artifacts;</li><li>VitePress contains only intentional Archie content;</li><li>build artifacts and installed dependencies are absent from source control;</li><li><code>task docs:serve</code> supports local authoring;</li><li><code>task docs:build</code> produces the deployable site;</li><li><code>task check</code> blocks stale or broken documentation;</li><li>GitHub Pages publishes the verified VitePress artifact.</li></ul><h2 id="implementation-references" tabindex="-1">Implementation references <a class="header-anchor" href="#implementaLine truncated
<script>window.__VP_HASH_MAP__=JSON.parse("{\"architecture_agent-system.md\":\"Coj6mPZw\",\"architecture_configuration.md\":\"BsVGi7ja\",\"architecture_dependencies-and-contracts.md\":\"ByRODJZC\",\"architecture_generated-documentation.md\":\"qELen1k6\",\"architecture_identity.md\":\"CB0DkYo9\",\"architecture_index.md\":\"DJpk2YHf\",\"architecture_messaging-and-work-intake.md\":\"Q7MxXQDB\",\"architecture_migration-decisions.md\":\"oN2eGfag\",\"architecture_organisation.md\":\"mAPb3vCC\",\"architecture_package-review.md\":\"7BZCENBd\",\"architecture_plugins-and-extensions.md\":\"DmzsC2M0\",\"architecture_policy.md\":\"4L33IZiY\",\"architecture_safe-change-and-recovery.md\":\"CdYeF0XF\",\"archive_archie-core-architecture.md\":\"Bqg5-owD\",\"archive_archie-core-skills-prd-v2.md\":\"D3RVdXag\",\"archive_archie-core-skills-prd.md\":\"D1oUBHEN\",\"archive_decisions.md\":\"DkenJ6mD\",\"archive_design.md\":\"BwF1bH5l\",\"archive_prds_multi-agent-collaboration.md\":\"zqWXF3O0\",\"archive_prds_typescript-plugin-engine.md\":\"DBR1GKuy\",\"archive_prds_yaegi-plugin-system.md\":\"V36uzfZI\",\"index.md\":\"BdS51Ijr\",\"prds_01-project-management.md\":\"DEpuIAgg\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Archie\",\"description\":\"Documentation for the Archie personal agent platform.\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/favicon.svg\",\"nav\":[{\"text\":\"Architecture\",\"link\":\"/architecture/\"}],\"sidebar\":{\"/architecture/\":[{\"text\":\"Architecture\",\"items\":[{\"text\":\"Overview\",\"link\":\"/architecture/\"},{\"text\":\"Repository Organisation\",\"link\":\"/architecture/organisation\"},{\"text\":\"Dependencies and Contracts\",\"link\":\"/architecture/dependencies-and-contracts\"},{\"text\":\"Agent System\",\"link\":\"/architecture/agent-system\"},{\"text\":\"Configuration\",\"link\":\"/architecture/configuration\"},{\"text\":\"Identity\",\"link\":\"/architecture/identity\"},{\"text\":\"Messaging and Work Intake\",\"link\":\"/architecture/messaging-and-work-intake\"},{\"text\":\"Plugins and Extensions\",\"link\":\"/architecture/plugins-and-extensions\"},{\"text\":\"Policy System\",\"link\":\"/architecture/policy\"},{\"text\":\"Safe Change and Recovery\",\"link\":\"/architecture/safe-change-and-recovery\"},{\"text\":\"Generated Documentation\",\"link\":\"/architecture/generated-documentation\"},{\"text\":\"Domain and Feature Review Procedure\",\"link\":\"/architecture/package-review\"},{\"text\":\"Migration Decisions\",\"link\":\"/architecture/migration-decisions\"}]}]},\"search\":{\"provider\":\"local\"},\"footer\":{\"message\":\"Built with VitePress.\",\"copyright\":\"Archie\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
</body>
</html>
-34
View File
@@ -1,34 +0,0 @@
<!DOCTYPE html>
<html lang="en-US" dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Identity | Archie</title>
<meta name="description" content="Documentation for the Archie personal agent platform.">
<meta name="generator" content="VitePress v1.6.4">
<link rel="preload stylesheet" href="/assets/style.C4BXn3EN.css" as="style">
<link rel="preload stylesheet" href="/vp-icons.css" as="style">
<script type="module" src="/assets/app.HIbJYLU1.js"></script>
<link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="modulepreload" href="/assets/chunks/theme.B97NJxv0.js">
<link rel="modulepreload" href="/assets/chunks/framework.BWuWLRhz.js">
<link rel="modulepreload" href="/assets/architecture_identity.md.CB0DkYo9.lean.js">
<link rel="icon" href="/favicon.svg">
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
</head>
<body>
<div id="app"><div class="Layout" data-v-cb931ff4><!--[--><!--]--><!--[--><span tabindex="-1" data-v-8ae66126></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-8ae66126>Skip to content</a><!--]--><!----><header class="VPNav" data-v-cb931ff4 data-v-a1925027><div class="VPNavBar" data-v-a1925027 data-v-2840085c><div class="wrapper" data-v-2840085c><div class="container" data-v-2840085c><div class="title" data-v-2840085c><div class="VPNavBarTitle has-sidebar" data-v-2840085c data-v-e7a29354><a class="title" href="/" data-v-e7a29354><!--[--><!--]--><!--[--><img class="VPImage logo" src="/favicon.svg" alt data-v-eec9b196><!--]--><span data-v-e7a29354>Archie</span><!--[--><!--]--></a></div></div><div class="content" data-v-2840085c><div class="content-body" data-v-2840085c><!--[--><!--]--><div class="VPNavBarSearch search" data-v-2840085c><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-2840085c data-v-ded89948><span id="main-nav-aria-label" class="visually-hidden" data-v-ded89948> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/architecture/" tabindex="0" data-v-ded89948 data-v-0a9a3d21><!--[--><span data-v-0a9a3d21>Architecture</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-2840085c data-v-4b074154><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-4b074154 data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-2840085c data-v-6ca47e2f data-v-b980f1c3><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-b980f1c3><span class="vpi-more-horizontal icon" data-v-b980f1c3></span></button><div class="menu" data-v-b980f1c3><div class="VPMenu" data-v-b980f1c3 data-v-a1767133><!----><!--[--><!--[--><!----><div class="group" data-v-6ca47e2f><div class="item appearance" data-v-6ca47e2f><p class="label" data-v-6ca47e2f>Appearance</p><div class="appearance-action" data-v-6ca47e2f><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-6ca47e2f data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-2840085c data-v-3597ebf2><span class="container" data-v-3597ebf2><span class="top" data-v-3597ebf2></span><span class="middle" data-v-3597ebf2></span><span class="bottom" data-v-3597ebf2></span></span></button></div></div></div></div><div class="divider" data-v-2840085c><div class="divider-line" data-v-2840085c></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-cb931ff4 data-v-c17e40bf><div class="container" data-v-c17e40bf><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-c17e40bf><span class="vpi-align-left menu-icon" data-v-c17e40bf></span><span class="menu-text" data-v-c17e40bf>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-c17e40bf data-v-88669269><button data-v-88669269>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-cb931ff4 data-v-f5090d1d><div class="curtain" data-v-f5090d1d></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-f5090d1d><span class="visually-hidden" id="sidebar-aria-label" data-v-f5090d1d> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-049afe89><section class="VPSidebarItem level-0 has-active" data-v-049afe89 data-v-ce191e9a><div class="item" role="button" tabindex="0" data-v-ce191e9a><div class="indicator" data-v-ce191e9a></div><h2 class="text" data-v-ce191e9a>Architecture</h2><!----></div><div class="items" data-v-ce191e9a><!--[--><div class="VPSidebarItem level-1 is-link" data-v-ce191e9a><div class="item" data-v-ce191e9a><div class="indicator" data-v-ce191e9a></div><a class="VPLink link link" href="/architecture/" data-v-ce19Line truncated
<span class="line"><span>active -&gt; suspended</span></span>
<span class="line"><span>suspended -&gt; active</span></span>
<span class="line"><span>active -&gt; retired</span></span>
<span class="line"><span>suspended -&gt; retired</span></span></code></pre></div><p><code>retired</code> has no outgoing transition.</p><p>Capability health is separate from identity lifecycle. Forge, model, channel, workspace, and other bindings report health independently. An active identity may be partially degraded without becoming suspended or retired. Runtime supervision isolates and restores affected bindings through the safe-change and recovery protocol.</p><h2 id="system-identity" tabindex="-1">System identity <a class="header-anchor" href="#system-identity" aria-label="Permalink to &quot;System identity&quot;">​</a></h2><p>Archie has exactly one built-in system identity. It is created during initial store bootstrap, is strictly always active, and cannot be suspended or retired. Its <code>IdentityID</code> and kind are immutable.</p><p>Startup, migration, supervision, remediation, and rollback actions performed by the application use the system identity. The system identity MUST NOT be delegated to individual identities. Every user, bot, service account, or other actor mutation records the identity that actually performed it.</p><p>System capabilities may independently become unhealthy or unavailable without changing the system identity.</p><h2 id="target-placement-and-contracts" tabindex="-1">Target placement and contracts <a class="header-anchor" href="#target-placement-and-contracts" aria-label="Permalink to &quot;Target placement and contracts&quot;">​</a></h2><p>The Identity domain lives at <code>internal/domain/identity</code>.</p><p>It owns:</p><ul><li><code>IdentityID</code>, identity kind, display name, lifecycle, version, and audit timestamps;</li><li>create, rename, suspend, reactivate, and retire commands;</li><li>corresponding lifecycle events;</li><li>the repository contract required for durable identity records;</li><li>lookup of current and historical identities.</li></ul><p>External account bindings and capability settings remain with the domains that use them and reference <code>IdentityID</code>.</p><h2 id="migration-constraints" tabindex="-1">Migration constraints <a class="header-anchor" href="#migration-constraints" aria-label="Permalink to &quot;Migration constraints&quot;">​</a></h2><p>Migration from the current string model MUST:</p><ul><li>bootstrap the permanent system identity;</li><li>assign stable IDs to configured identities without losing their names;</li><li>replace empty-string legacy ownership with the system identity;</li><li>migrate tasks and sessions to canonical identity references;</li><li>include identity where task uniqueness and transport deduplication require independent ownership;</li><li>route container RPC through the task owner&#39;s capability bindings;</li><li>retain historical resolution after rename, suspension, or retirement;</li><li>remove identity-string equality from authentication or access semantics.</li></ul><p>This completes the foundation required to restructure the current Identity behaviour. Exact storage schemas and Go method signatures belong to implementation design, not this architecture review.</p><h2 id="lifecycle-1" tabindex="-1">Lifecycle <a class="header-anchor" href="#lifecycle-1" aria-label="Permalink to &quot;Lifecycle&quot;">​</a></h2><p>Identity lifecycle is deliberately small:</p><ul><li><code>active</code>: may participate in runtime composition;</li><li><code>suspended</code>: deliberately prevented from initiating new work while ownership and history remain;</li><li><code>retired</code>: terminal, unable to initiate work, and permanently retained for attribution.</li></ul><p>Allowed transitions are:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>create -&gt; active</span></span>
<span class="line"><span>active -&gt; suspended</span></span>
<span class="line"><span>suspended -&gt; active</span></span>
<span class="line"><span>active -&gt; retired</span></span>
<span class="line"><span>suspended -&gt; retired</span></span></code></pre></div><p><code>retired</code> has no outgoing transition.</p><p>Capability health is separate from identity lifecycle. Forge, model, channel, workspace, and other bindings report health independently. An active identity may be partially degraded without becoming suspended or retired. Runtime supervision isolates and restores affected bindings through the safe-change and recovery protocol.</p><h2 id="explicit-non-responsibilities" tabindex="-1">Explicit non-responsibilities <a class="header-anchor" href="#explicit-non-responsibilities" aria-label="Permalink to &quot;Explicit non-responsibilities&quot;">​</a></h2><p>Identity is not authentication and is not access control.</p><p>The current architecture does not require authentication or authorization. Those capabilities MAY be introduced later if deployment or product needs justify them. They MUST remain separate from the identity model.</p><p>An identity reference therefore proves attribution within Archie&#39;s trusted system model; it does not by itself prove credentials or permission.</p><h2 id="per-identity-configuration" tabindex="-1">Per-identity configuration <a class="header-anchor" href="#per-identity-configuration" aria-label="Permalink to &quot;Per-identity configuration&quot;">​</a></h2><p>Values selected for an identity remain external configuration values. At composition time they are split into the runtime settings owned by the affected domains and correlated by identity reference.</p><p>The existing <code>IdentityConfig</code> aggregate MUST be dissolved. Forge accounts, repositories, models, providers, workspace behaviour, polling, budgets, notifications, and transport namespaces retain their respective owners.</p><h2 id="audit" tabindex="-1">Audit <a class="header-anchor" href="#audit" aria-label="Permalink to &quot;Audit&quot;">​</a></h2><p>Configuration changes and other state changes are actions attributed to an identity. System-initiated changes use the system identity. Their audit records MUST preserve the acting identity, the target, and the resulting change.</p><p>The command ownership and persistence mechanism for configuration changes is a separate configuration-management decision.</p><h2 id="current-implementation" tabindex="-1">Current implementation <a class="header-anchor" href="#current-implementation" aria-label="Permalink to &quot;Current implementation&quot;">​</a></h2><p>Identity is not currently implemented as a domain. It is a collection of string fields and process-local associations:</p><ul><li><code>config.IdentityConfig.Name</code> is the daemon routing key.</li><li><code>config.IdentityConfig.BotUser</code> is the external forge and Git author name.</li><li><code>daemon.IdentityRunner</code> bundles the configured name with a forge client, worktree manager, repository list, configuration subset, logger, and polling goroutine.</li><li><code>store.Task.Identity</code> persists the configured name on tasks.</li><li>NATS task messages copy the same configured name.</li><li>gateway routing accepts an identity name and uses it to select a repository profile.</li><li>gateway sessions persist <code>BotUser</code>, not the configured identity name.</li></ul><p>There is no identity registry, identity record, identity lifecycle state, identity persistence, or identity command/event model. Removing an identity from configuration makes existing task ownership unresolvable.</p><p>An empty identity string selects the legacy single-identity path. This gives the empty string behavioural meaning rather than representing a real system identity.</p><h2 id="current-enforcement-and-isolation" tabindex="-1">Current enforcement and isolation <a class="header-anchor" href="#current-enforcement-and-isolation" aria-label="Permalink to &quot;Current enforcement and isolation&quot;">​</a></h2><p>The current implementation uses identity equality as an authorization check for chat task approval and cancellation. This conflicts with the approved rule that identity is attribution rather than authentication or access control and must be reassigned to an appropriate task-ownership or future access policy.</p><p>Focused tests verify that:</p><ul><li>a task resolves the forge client and repository list associated with its configured identity name;</li><li>cross-identity repository profiles do not leak;</li><li>chat task creation propagates the selected identity;</li><li>task and NellDB persistence retain the identity string;</li><li>chat task control rejects a different identity string.</li></ul><h2 id="current-hazards" tabindex="-1">Current hazards <a class="header-anchor" href="#current-hazards" aria-label="Permalink to &quot;Current hazards&quot;">​</a></h2><ul><li>SQLite task uniqueness is <code>(owner, repo, issue_number)</code> and excludes identity. Two identities discovering the same forge issue cannot own distinct task records.</li><li>NATS deduplication Line truncated
<script>window.__VP_HASH_MAP__=JSON.parse("{\"architecture_agent-system.md\":\"Coj6mPZw\",\"architecture_configuration.md\":\"BsVGi7ja\",\"architecture_dependencies-and-contracts.md\":\"ByRODJZC\",\"architecture_generated-documentation.md\":\"qELen1k6\",\"architecture_identity.md\":\"CB0DkYo9\",\"architecture_index.md\":\"DJpk2YHf\",\"architecture_messaging-and-work-intake.md\":\"Q7MxXQDB\",\"architecture_migration-decisions.md\":\"oN2eGfag\",\"architecture_organisation.md\":\"mAPb3vCC\",\"architecture_package-review.md\":\"7BZCENBd\",\"architecture_plugins-and-extensions.md\":\"DmzsC2M0\",\"architecture_policy.md\":\"4L33IZiY\",\"architecture_safe-change-and-recovery.md\":\"CdYeF0XF\",\"archive_archie-core-architecture.md\":\"Bqg5-owD\",\"archive_archie-core-skills-prd-v2.md\":\"D3RVdXag\",\"archive_archie-core-skills-prd.md\":\"D1oUBHEN\",\"archive_decisions.md\":\"DkenJ6mD\",\"archive_design.md\":\"BwF1bH5l\",\"archive_prds_multi-agent-collaboration.md\":\"zqWXF3O0\",\"archive_prds_typescript-plugin-engine.md\":\"DBR1GKuy\",\"archive_prds_yaegi-plugin-system.md\":\"V36uzfZI\",\"index.md\":\"BdS51Ijr\",\"prds_01-project-management.md\":\"DEpuIAgg\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Archie\",\"description\":\"Documentation for the Archie personal agent platform.\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/favicon.svg\",\"nav\":[{\"text\":\"Architecture\",\"link\":\"/architecture/\"}],\"sidebar\":{\"/architecture/\":[{\"text\":\"Architecture\",\"items\":[{\"text\":\"Overview\",\"link\":\"/architecture/\"},{\"text\":\"Repository Organisation\",\"link\":\"/architecture/organisation\"},{\"text\":\"Dependencies and Contracts\",\"link\":\"/architecture/dependencies-and-contracts\"},{\"text\":\"Agent System\",\"link\":\"/architecture/agent-system\"},{\"text\":\"Configuration\",\"link\":\"/architecture/configuration\"},{\"text\":\"Identity\",\"link\":\"/architecture/identity\"},{\"text\":\"Messaging and Work Intake\",\"link\":\"/architecture/messaging-and-work-intake\"},{\"text\":\"Plugins and Extensions\",\"link\":\"/architecture/plugins-and-extensions\"},{\"text\":\"Policy System\",\"link\":\"/architecture/policy\"},{\"text\":\"Safe Change and Recovery\",\"link\":\"/architecture/safe-change-and-recovery\"},{\"text\":\"Generated Documentation\",\"link\":\"/architecture/generated-documentation\"},{\"text\":\"Domain and Feature Review Procedure\",\"link\":\"/architecture/package-review\"},{\"text\":\"Migration Decisions\",\"link\":\"/architecture/migration-decisions\"}]}]},\"search\":{\"provider\":\"local\"},\"footer\":{\"message\":\"Built with VitePress.\",\"copyright\":\"Archie\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
</body>
</html>
-26
View File
@@ -1,26 +0,0 @@
<!DOCTYPE html>
<html lang="en-US" dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Architecture | Archie</title>
<meta name="description" content="Documentation for the Archie personal agent platform.">
<meta name="generator" content="VitePress v1.6.4">
<link rel="preload stylesheet" href="/assets/style.C4BXn3EN.css" as="style">
<link rel="preload stylesheet" href="/vp-icons.css" as="style">
<script type="module" src="/assets/app.HIbJYLU1.js"></script>
<link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="modulepreload" href="/assets/chunks/theme.B97NJxv0.js">
<link rel="modulepreload" href="/assets/chunks/framework.BWuWLRhz.js">
<link rel="modulepreload" href="/assets/architecture_index.md.DJpk2YHf.lean.js">
<link rel="icon" href="/favicon.svg">
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
</head>
<body>
<div id="app"><div class="Layout" data-v-cb931ff4><!--[--><!--]--><!--[--><span tabindex="-1" data-v-8ae66126></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-8ae66126>Skip to content</a><!--]--><!----><header class="VPNav" data-v-cb931ff4 data-v-a1925027><div class="VPNavBar" data-v-a1925027 data-v-2840085c><div class="wrapper" data-v-2840085c><div class="container" data-v-2840085c><div class="title" data-v-2840085c><div class="VPNavBarTitle has-sidebar" data-v-2840085c data-v-e7a29354><a class="title" href="/" data-v-e7a29354><!--[--><!--]--><!--[--><img class="VPImage logo" src="/favicon.svg" alt data-v-eec9b196><!--]--><span data-v-e7a29354>Archie</span><!--[--><!--]--></a></div></div><div class="content" data-v-2840085c><div class="content-body" data-v-2840085c><!--[--><!--]--><div class="VPNavBarSearch search" data-v-2840085c><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-2840085c data-v-ded89948><span id="main-nav-aria-label" class="visually-hidden" data-v-ded89948> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink active" href="/architecture/" tabindex="0" data-v-ded89948 data-v-0a9a3d21><!--[--><span data-v-0a9a3d21>Architecture</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-2840085c data-v-4b074154><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-4b074154 data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-2840085c data-v-6ca47e2f data-v-b980f1c3><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-b980f1c3><span class="vpi-more-horizontal icon" data-v-b980f1c3></span></button><div class="menu" data-v-b980f1c3><div class="VPMenu" data-v-b980f1c3 data-v-a1767133><!----><!--[--><!--[--><!----><div class="group" data-v-6ca47e2f><div class="item appearance" data-v-6ca47e2f><p class="label" data-v-6ca47e2f>Appearance</p><div class="appearance-action" data-v-6ca47e2f><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-6ca47e2f data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-2840085c data-v-3597ebf2><span class="container" data-v-3597ebf2><span class="top" data-v-3597ebf2></span><span class="middle" data-v-3597ebf2></span><span class="bottom" data-v-3597ebf2></span></span></button></div></div></div></div><div class="divider" data-v-2840085c><div class="divider-line" data-v-2840085c></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-cb931ff4 data-v-c17e40bf><div class="container" data-v-c17e40bf><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-c17e40bf><span class="vpi-align-left menu-icon" data-v-c17e40bf></span><span class="menu-text" data-v-c17e40bf>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-c17e40bf data-v-88669269><button data-v-88669269>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-cb931ff4 data-v-f5090d1d><div class="curtain" data-v-f5090d1d></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-f5090d1d><span class="visually-hidden" id="sidebar-aria-label" data-v-f5090d1d> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-049afe89><section class="VPSidebarItem level-0 has-active" data-v-049afe89 data-v-ce191e9a><div class="item" role="button" tabindex="0" data-v-ce191e9a><div class="indicator" data-v-ce191e9a></div><h2 class="text" data-v-ce191e9a>Architecture</h2><!----></div><div class="items" data-v-ce191e9a><!--[--><div class="VPSidebarItem level-1 is-link" data-v-ce191e9a><div class="item" data-v-ce191e9a><div class="indicator" data-v-ce191e9a></div><a class="VPLink link link" href="/architecture/" dataLine truncated
<script>window.__VP_HASH_MAP__=JSON.parse("{\"architecture_agent-system.md\":\"Coj6mPZw\",\"architecture_configuration.md\":\"BsVGi7ja\",\"architecture_dependencies-and-contracts.md\":\"ByRODJZC\",\"architecture_generated-documentation.md\":\"qELen1k6\",\"architecture_identity.md\":\"CB0DkYo9\",\"architecture_index.md\":\"DJpk2YHf\",\"architecture_messaging-and-work-intake.md\":\"Q7MxXQDB\",\"architecture_migration-decisions.md\":\"oN2eGfag\",\"architecture_organisation.md\":\"mAPb3vCC\",\"architecture_package-review.md\":\"7BZCENBd\",\"architecture_plugins-and-extensions.md\":\"DmzsC2M0\",\"architecture_policy.md\":\"4L33IZiY\",\"architecture_safe-change-and-recovery.md\":\"CdYeF0XF\",\"archive_archie-core-architecture.md\":\"Bqg5-owD\",\"archive_archie-core-skills-prd-v2.md\":\"D3RVdXag\",\"archive_archie-core-skills-prd.md\":\"D1oUBHEN\",\"archive_decisions.md\":\"DkenJ6mD\",\"archive_design.md\":\"BwF1bH5l\",\"archive_prds_multi-agent-collaboration.md\":\"zqWXF3O0\",\"archive_prds_typescript-plugin-engine.md\":\"DBR1GKuy\",\"archive_prds_yaegi-plugin-system.md\":\"V36uzfZI\",\"index.md\":\"BdS51Ijr\",\"prds_01-project-management.md\":\"DEpuIAgg\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Archie\",\"description\":\"Documentation for the Archie personal agent platform.\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/favicon.svg\",\"nav\":[{\"text\":\"Architecture\",\"link\":\"/architecture/\"}],\"sidebar\":{\"/architecture/\":[{\"text\":\"Architecture\",\"items\":[{\"text\":\"Overview\",\"link\":\"/architecture/\"},{\"text\":\"Repository Organisation\",\"link\":\"/architecture/organisation\"},{\"text\":\"Dependencies and Contracts\",\"link\":\"/architecture/dependencies-and-contracts\"},{\"text\":\"Agent System\",\"link\":\"/architecture/agent-system\"},{\"text\":\"Configuration\",\"link\":\"/architecture/configuration\"},{\"text\":\"Identity\",\"link\":\"/architecture/identity\"},{\"text\":\"Messaging and Work Intake\",\"link\":\"/architecture/messaging-and-work-intake\"},{\"text\":\"Plugins and Extensions\",\"link\":\"/architecture/plugins-and-extensions\"},{\"text\":\"Policy System\",\"link\":\"/architecture/policy\"},{\"text\":\"Safe Change and Recovery\",\"link\":\"/architecture/safe-change-and-recovery\"},{\"text\":\"Generated Documentation\",\"link\":\"/architecture/generated-documentation\"},{\"text\":\"Domain and Feature Review Procedure\",\"link\":\"/architecture/package-review\"},{\"text\":\"Migration Decisions\",\"link\":\"/architecture/migration-decisions\"}]}]},\"search\":{\"provider\":\"local\"},\"footer\":{\"message\":\"Built with VitePress.\",\"copyright\":\"Archie\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
</body>
</html>
@@ -1,31 +0,0 @@
<!DOCTYPE html>
<html lang="en-US" dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Messaging and Work Intake | Archie</title>
<meta name="description" content="Documentation for the Archie personal agent platform.">
<meta name="generator" content="VitePress v1.6.4">
<link rel="preload stylesheet" href="/assets/style.C4BXn3EN.css" as="style">
<link rel="preload stylesheet" href="/vp-icons.css" as="style">
<script type="module" src="/assets/app.HIbJYLU1.js"></script>
<link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="modulepreload" href="/assets/chunks/theme.B97NJxv0.js">
<link rel="modulepreload" href="/assets/chunks/framework.BWuWLRhz.js">
<link rel="modulepreload" href="/assets/architecture_messaging-and-work-intake.md.Q7MxXQDB.lean.js">
<link rel="icon" href="/favicon.svg">
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
</head>
<body>
<div id="app"><div class="Layout" data-v-cb931ff4><!--[--><!--]--><!--[--><span tabindex="-1" data-v-8ae66126></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-8ae66126>Skip to content</a><!--]--><!----><header class="VPNav" data-v-cb931ff4 data-v-a1925027><div class="VPNavBar" data-v-a1925027 data-v-2840085c><div class="wrapper" data-v-2840085c><div class="container" data-v-2840085c><div class="title" data-v-2840085c><div class="VPNavBarTitle has-sidebar" data-v-2840085c data-v-e7a29354><a class="title" href="/" data-v-e7a29354><!--[--><!--]--><!--[--><img class="VPImage logo" src="/favicon.svg" alt data-v-eec9b196><!--]--><span data-v-e7a29354>Archie</span><!--[--><!--]--></a></div></div><div class="content" data-v-2840085c><div class="content-body" data-v-2840085c><!--[--><!--]--><div class="VPNavBarSearch search" data-v-2840085c><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-2840085c data-v-ded89948><span id="main-nav-aria-label" class="visually-hidden" data-v-ded89948> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/architecture/" tabindex="0" data-v-ded89948 data-v-0a9a3d21><!--[--><span data-v-0a9a3d21>Architecture</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-2840085c data-v-4b074154><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-4b074154 data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-2840085c data-v-6ca47e2f data-v-b980f1c3><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-b980f1c3><span class="vpi-more-horizontal icon" data-v-b980f1c3></span></button><div class="menu" data-v-b980f1c3><div class="VPMenu" data-v-b980f1c3 data-v-a1767133><!----><!--[--><!--[--><!----><div class="group" data-v-6ca47e2f><div class="item appearance" data-v-6ca47e2f><p class="label" data-v-6ca47e2f>Appearance</p><div class="appearance-action" data-v-6ca47e2f><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-6ca47e2f data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-2840085c data-v-3597ebf2><span class="container" data-v-3597ebf2><span class="top" data-v-3597ebf2></span><span class="middle" data-v-3597ebf2></span><span class="bottom" data-v-3597ebf2></span></span></button></div></div></div></div><div class="divider" data-v-2840085c><div class="divider-line" data-v-2840085c></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-cb931ff4 data-v-c17e40bf><div class="container" data-v-c17e40bf><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-c17e40bf><span class="vpi-align-left menu-icon" data-v-c17e40bf></span><span class="menu-text" data-v-c17e40bf>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-c17e40bf data-v-88669269><button data-v-88669269>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-cb931ff4 data-v-f5090d1d><div class="curtain" data-v-f5090d1d></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-f5090d1d><span class="visually-hidden" id="sidebar-aria-label" data-v-f5090d1d> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-049afe89><section class="VPSidebarItem level-0 has-active" data-v-049afe89 data-v-ce191e9a><div class="item" role="button" tabindex="0" data-v-ce191e9a><div class="indicator" data-v-ce191e9a></div><h2 class="text" data-v-ce191e9a>Architecture</h2><!----></div><div class="items" data-v-ce191e9a><!--[--><div class="VPSidebarItem level-1 is-link" data-v-ce191e9a><div class="item" data-v-ce191e9a><div class="indicator" data-v-ce191e9a></div><a class="VPLink link link" href="/architecture/" data-v-ce19Line truncated
<span class="line"><span>+ UserIdentityID</span></span>
<span class="line"><span>+ ChannelBindingID</span></span>
<span class="line"><span>+ ExternalConversationID</span></span>
<span class="line"><span>+ ThreadID</span></span></code></pre></div><p><code>ThreadID</code> has an explicit empty value for channels without threads. No element of this key may be replaced by a display name, configured bot username, channel type, or other mutable label.</p><p>Agent and user memory continue across conversations according to their memory scope. Immediate conversation history and delivery correlation remain isolated to the identified channel conversation or thread. Moving between Telegram, email, or another channel does not create a new Agent or user, but it does create a distinct conversation unless an explicit linking operation relates them.</p><p>Conversation and message events support projections for channel-entry metrics, use cases, volumes, outcomes, latency, capability usage, and other product or operational analysis. Metrics are derived read models; they MUST NOT become mutable counters embedded in the conversation aggregate or change message routing semantics.</p><h2 id="canonical-messages" tabindex="-1">Canonical messages <a class="header-anchor" href="#canonical-messages" aria-label="Permalink to &quot;Canonical messages&quot;">​</a></h2><p>Every inbound, assistant, tool-call, and tool-result message has an immutable application-generated MessageID. Platform identifiers are external correlation, not substitutes for the canonical ID.</p><p>Messages are addressable because an interaction is more than text. A message may contain assistant content, reasoning data subject to its retention policy, one or more tool calls, a tool result with authoritative execution metadata, attachments, reply relationships, edits, or other typed content. Stable MessageIDs also allow sessions to branch from an exact prior point.</p><p>The canonical session and message implementation must supply:</p><ul><li>application-generated stable message IDs;</li><li>user, assistant, and tool roles;</li><li>assistant tool calls and correlated tool-result messages;</li><li>authoritative tool-result status, timing, error, truncation, and size metadata;</li><li>session lifecycle and active-request state;</li><li>session-to-agent-instance and parent-session lineage;</li><li>durable SQLite round trips and timestamp validation.</li></ul><p>These semantics must use the confirmed Agent, user, channel-binding, and conversation ownership model.</p><p>The canonical message store MUST preserve messages as immutable records and represent later edits, deletions, and branches through related records or events.</p><p>Archie requires exact branch-point correlation using stable MessageIDs.</p><h2 id="conversation-branches" tabindex="-1">Conversation branches <a class="header-anchor" href="#conversation-branches" aria-label="Permalink to &quot;Conversation branches&quot;">​</a></h2><p>A branch is a continuation of a previous conversation at an exact message. A child conversation records:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>ParentConversationID</span></span>
<span class="line"><span>ForkMessageID</span></span></code></pre></div><p>Messages remain an append-only linear sequence within each conversation. The child&#39;s effective initial context is the parent&#39;s history through <code>ForkMessageID</code>; messages after that point in the parent are not inherited.</p><p>After the fork, parent and child are isolated:</p><ul><li>child messages, tool calls, tool results, capability actions, and errors do not appear in the parent conversation;</li><li>later parent messages do not silently enter the child;</li><li>returning to the parent resumes its unchanged history;</li><li>the child may itself be branched using the same rules;</li><li>branch lineage remains queryable for navigation, audit, and metrics.</li></ul><p>This supports building substantial context about a subject and then performing one or more contextual subtasks without polluting the original conversation. For example, a user may branch from a project discussion, create Jira issues in the child using inherited context, and then return to the project discussion without adding the Jira tool transcript to the parent.</p><p>Branching does not copy mutable message rows. History is resolved through the immutable parent conversation and fork MessageID, followed by the child&#39;s own message sequence.</p><p>Branch isolation applies to conversation history, not to Agent learning or memory. A memory action performed in a branch has exactly the same semantics as the same action performed in any other conversation. It writes to its selected global, agent-wide, user-wide, or Agent-user relationship scope.</p><p>Memory provenance MAY retain the source ConversationID and MessageIDs for explanation and audit. Retrieval and effect are determined by memory scope and access rules, not by the conversation from which the memory originated. Returning to a parent does not insert the child&#39;s tool transcript into the parent history, but scoped memories learned in the child remain available to future retrieval wherever that scope is visible.</p><p>Changing sessions or branching therefore controls immediate conversational context without preventing the Agent from learning durable knowledge.</p><h2 id="target-ownership" tabindex="-1">Target ownership <a class="header-anchor" href="#target-ownership" aria-label="Permalink to &quot;Target ownership&quot;">​</a></h2><p>The Messaging domain lives at <code>internal/domain/messaging</code>. It owns:</p><ul><li>canonical Messages and typed message content;</li><li>Conversations, branches, and lineage;</li><li>channel bindings and external source correlation;</li><li>replies, acknowledgements, and outbound delivery attempts;</li><li>message and conversation lifecycle events;</li><li>domain-defined repository and delivery service contracts;</li><li>projections required for conversation navigation and metrics.</li></ul><p>Work intake is a separate cohesive domain at <code>internal/domain/workintake</code>. It owns admission, validation, deterministic routing, and accepted work requests for the optional transition into durable workflow-backed execution.</p><p>Telegram, email, webhook, forge, Jira, and future messaging systems are infrastructure adapters implementing Messaging contracts. They are users of the domain; they do not own Messages, Conversations, work admission, or WorkflowExecution semantics.</p><p>The Agent decides whether an ordinary interaction is answered directly, uses a capability, changes or retrieves Agent-owned information, or proposes durable workflow-backed work.</p><p>Explicitly configured automation MAY enter work intake without a conversational Agent turn when the external trigger and admission rule already unambiguously request durable work. This avoids spending an LLM turn to rediscover a deterministic routing decision.</p><p>When an interaction requires durable workflow-backed execution:</p><ol><li>a channel adapter produces a channel-neutral inbound message;</li><li>the acting agent handles or interprets the interaction;</li><li>work intake validates, admits, and routes a proposed work request;</li><li>work intake emits an accepted work request with its source correlation, acting identity, requested outcome, inputs, and routing evidence;</li><li>the Agent System consumes that request, selects a specific Workflow version, and creates the WorkflowExecution.</li></ol><p>The accepted work request is a cross-domain handoff, not an alternate execution aggregate. The Agent System is the sole authority that creates a valid WorkflowExecution.</p><p>An interaction MAY instead be completed directly by an agent turn, delegated to a tool or capability, recorded as a note or reminder, answered conversationally, or retained for later context. Those paths MUST NOT require a Workflow or WorkflowExecution.</p><p>A Workflow MAY add reusable, versioned structure to any of those behaviours. Scheduled personal-assistant routines, message triage, reminders, infrastructure operLine truncated
<script>window.__VP_HASH_MAP__=JSON.parse("{\"architecture_agent-system.md\":\"Coj6mPZw\",\"architecture_configuration.md\":\"BsVGi7ja\",\"architecture_dependencies-and-contracts.md\":\"ByRODJZC\",\"architecture_generated-documentation.md\":\"qELen1k6\",\"architecture_identity.md\":\"CB0DkYo9\",\"architecture_index.md\":\"DJpk2YHf\",\"architecture_messaging-and-work-intake.md\":\"Q7MxXQDB\",\"architecture_migration-decisions.md\":\"oN2eGfag\",\"architecture_organisation.md\":\"mAPb3vCC\",\"architecture_package-review.md\":\"7BZCENBd\",\"architecture_plugins-and-extensions.md\":\"DmzsC2M0\",\"architecture_policy.md\":\"4L33IZiY\",\"architecture_safe-change-and-recovery.md\":\"CdYeF0XF\",\"archive_archie-core-architecture.md\":\"Bqg5-owD\",\"archive_archie-core-skills-prd-v2.md\":\"D3RVdXag\",\"archive_archie-core-skills-prd.md\":\"D1oUBHEN\",\"archive_decisions.md\":\"DkenJ6mD\",\"archive_design.md\":\"BwF1bH5l\",\"archive_prds_multi-agent-collaboration.md\":\"zqWXF3O0\",\"archive_prds_typescript-plugin-engine.md\":\"DBR1GKuy\",\"archive_prds_yaegi-plugin-system.md\":\"V36uzfZI\",\"index.md\":\"BdS51Ijr\",\"prds_01-project-management.md\":\"DEpuIAgg\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Archie\",\"description\":\"Documentation for the Archie personal agent platform.\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/favicon.svg\",\"nav\":[{\"text\":\"Architecture\",\"link\":\"/architecture/\"}],\"sidebar\":{\"/architecture/\":[{\"text\":\"Architecture\",\"items\":[{\"text\":\"Overview\",\"link\":\"/architecture/\"},{\"text\":\"Repository Organisation\",\"link\":\"/architecture/organisation\"},{\"text\":\"Dependencies and Contracts\",\"link\":\"/architecture/dependencies-and-contracts\"},{\"text\":\"Agent System\",\"link\":\"/architecture/agent-system\"},{\"text\":\"Configuration\",\"link\":\"/architecture/configuration\"},{\"text\":\"Identity\",\"link\":\"/architecture/identity\"},{\"text\":\"Messaging and Work Intake\",\"link\":\"/architecture/messaging-and-work-intake\"},{\"text\":\"Plugins and Extensions\",\"link\":\"/architecture/plugins-and-extensions\"},{\"text\":\"Policy System\",\"link\":\"/architecture/policy\"},{\"text\":\"Safe Change and Recovery\",\"link\":\"/architecture/safe-change-and-recovery\"},{\"text\":\"Generated Documentation\",\"link\":\"/architecture/generated-documentation\"},{\"text\":\"Domain and Feature Review Procedure\",\"link\":\"/architecture/package-review\"},{\"text\":\"Migration Decisions\",\"link\":\"/architecture/migration-decisions\"}]}]},\"search\":{\"provider\":\"local\"},\"footer\":{\"message\":\"Built with VitePress.\",\"copyright\":\"Archie\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
</body>
</html>
@@ -1,40 +0,0 @@
<!DOCTYPE html>
<html lang="en-US" dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Architecture Migration Decisions | Archie</title>
<meta name="description" content="Documentation for the Archie personal agent platform.">
<meta name="generator" content="VitePress v1.6.4">
<link rel="preload stylesheet" href="/assets/style.C4BXn3EN.css" as="style">
<link rel="preload stylesheet" href="/vp-icons.css" as="style">
<script type="module" src="/assets/app.HIbJYLU1.js"></script>
<link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="modulepreload" href="/assets/chunks/theme.B97NJxv0.js">
<link rel="modulepreload" href="/assets/chunks/framework.BWuWLRhz.js">
<link rel="modulepreload" href="/assets/architecture_migration-decisions.md.oN2eGfag.lean.js">
<link rel="icon" href="/favicon.svg">
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
</head>
<body>
<div id="app"><div class="Layout" data-v-cb931ff4><!--[--><!--]--><!--[--><span tabindex="-1" data-v-8ae66126></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-8ae66126>Skip to content</a><!--]--><!----><header class="VPNav" data-v-cb931ff4 data-v-a1925027><div class="VPNavBar" data-v-a1925027 data-v-2840085c><div class="wrapper" data-v-2840085c><div class="container" data-v-2840085c><div class="title" data-v-2840085c><div class="VPNavBarTitle has-sidebar" data-v-2840085c data-v-e7a29354><a class="title" href="/" data-v-e7a29354><!--[--><!--]--><!--[--><img class="VPImage logo" src="/favicon.svg" alt data-v-eec9b196><!--]--><span data-v-e7a29354>Archie</span><!--[--><!--]--></a></div></div><div class="content" data-v-2840085c><div class="content-body" data-v-2840085c><!--[--><!--]--><div class="VPNavBarSearch search" data-v-2840085c><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-2840085c data-v-ded89948><span id="main-nav-aria-label" class="visually-hidden" data-v-ded89948> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/architecture/" tabindex="0" data-v-ded89948 data-v-0a9a3d21><!--[--><span data-v-0a9a3d21>Architecture</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-2840085c data-v-4b074154><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-4b074154 data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-2840085c data-v-6ca47e2f data-v-b980f1c3><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-b980f1c3><span class="vpi-more-horizontal icon" data-v-b980f1c3></span></button><div class="menu" data-v-b980f1c3><div class="VPMenu" data-v-b980f1c3 data-v-a1767133><!----><!--[--><!--[--><!----><div class="group" data-v-6ca47e2f><div class="item appearance" data-v-6ca47e2f><p class="label" data-v-6ca47e2f>Appearance</p><div class="appearance-action" data-v-6ca47e2f><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-6ca47e2f data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-2840085c data-v-3597ebf2><span class="container" data-v-3597ebf2><span class="top" data-v-3597ebf2></span><span class="middle" data-v-3597ebf2></span><span class="bottom" data-v-3597ebf2></span></span></button></div></div></div></div><div class="divider" data-v-2840085c><div class="divider-line" data-v-2840085c></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-cb931ff4 data-v-c17e40bf><div class="container" data-v-c17e40bf><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-c17e40bf><span class="vpi-align-left menu-icon" data-v-c17e40bf></span><span class="menu-text" data-v-c17e40bf>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-c17e40bf data-v-88669269><button data-v-88669269>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-cb931ff4 data-v-f5090d1d><div class="curtain" data-v-f5090d1d></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-f5090d1d><span class="visually-hidden" id="sidebar-aria-label" data-v-f5090d1d> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-049afe89><section class="VPSidebarItem level-0 has-active" data-v-049afe89 data-v-ce191e9a><div class="item" role="button" tabindex="0" data-v-ce191e9a><div class="indicator" data-v-ce191e9a></div><h2 class="text" data-v-ce191e9a>Architecture</h2><!----></div><div class="items" data-v-ce191e9a><!--[--><div class="VPSidebarItem level-1 is-link" data-v-ce191e9a><div class="item" data-v-ce191e9a><div class="indicator" data-v-ce191e9a></div><a class="VPLink link link" href="/architecture/" data-v-ce19Line truncated
<span class="line"><span> identity/</span></span>
<span class="line"><span> agent/</span></span>
<span class="line"><span> workflow/</span></span>
<span class="line"><span> messaging/</span></span>
<span class="line"><span> workintake/</span></span>
<span class="line"><span> plugin/</span></span></code></pre></div><ul><li><code>identity</code> owns persistent actors, lifecycle, ownership, attribution, and audit identity.</li><li><code>agent</code> owns persistent assistants, specialisation, instructions, model-independent continuity, capability context, and associations with identity and memory.</li><li><code>workflow</code> is a separate domain. It owns reusable, versioned Workflow definitions, WorkflowSteps, WorkflowExecutions, StepExecutions, Attempts, outcomes, and typed Workflow plugin contracts.</li><li><code>messaging</code> owns canonical Messages, Conversations, branches, channel and source correlation, replies, acknowledgements, delivery attempts, events, and projections.</li><li><code>workintake</code> owns admission, validation, deterministic routing, and accepted work requests for the optional transition into durable workflow-backed execution.</li><li><code>plugin</code> owns generic plugin identity, discovery, compatibility, and lifecycle mechanics. It remains metadata-only; capability semantics and typed registration belong to the owning domain.</li></ul><p>Memory&#39;s final package placement remains undecided pending focused review of the existing implementation.</p><p>The following are approved shared or composition packages, not domains:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>internal/eventbus/</span></span>
<span class="line"><span>internal/policy/</span></span>
<span class="line"><span>internal/infrastructure/</span></span>
<span class="line"><span>internal/app/archied/</span></span>
<span class="line"><span>internal/app/agentworker/</span></span></code></pre></div><h2 id="remaining-migration-decisions" tabindex="-1">Remaining migration decisions <a class="header-anchor" href="#remaining-migration-decisions" aria-label="Permalink to &quot;Remaining migration decisions&quot;">​</a></h2><h3 id="_1-complete-package-destination-map" tabindex="-1">1. Complete package destination map <a class="header-anchor" href="#_1-complete-package-destination-map" aria-label="Permalink to &quot;1. Complete package destination map&quot;">​</a></h3><p>Every current package MUST receive one explicit disposition:</p><ul><li>move into a confirmed domain;</li><li>move under infrastructure as an implementation of a domain-owned contract;</li><li>move into application composition;</li><li>merge with an identified duplicate;</li><li>remain as an approved shared application contract;</li><li>move to a plugin, extra, deployment, example, or generated artifact;</li><li>be deleted after its replacement is proven.</li></ul><p>The largest unreviewed areas include memory, tools and capabilities, workspace and worktree behaviour, gates, storage, events, web UI, containers, RPC packages, release management, and scheduling.</p><p>The destination matrix MUST name the behaviour owner, target path, dependencies to remove, state and contracts to preserve, migration prerequisites, and deletion criteria.</p><h3 id="_2-session-and-messaging-migration" tabindex="-1">2. Session and Messaging migration <a class="header-anchor" href="#_2-session-and-messaging-migration" aria-label="Permalink to &quot;2. Session and Messaging migration&quot;">​</a></h3><p>The existing session implementation is the migration baseline. The migration must decide:</p><ul><li>which session and message components are retained or adapted;</li><li>how Agent, user, channel, Conversation, and branch ownership are added;</li><li>how Archie&#39;s parallel gateway session implementation is replaced;</li><li>how canonical Messages become immutable persisted records;</li><li>how existing NellDB sessions and messages are migrated;</li><li>how outbound delivery, retry, acknowledgement, deduplication, and failure semantics are represented;</li><li>how current Telegram, email, webhook, forge, and Jira integrations migrate to Messaging infrastructure adapters.</li></ul><p>The following are already decided and MUST NOT be reopened without contradictory implementation evidence:</p><ul><li>the composite Conversation identity;</li><li>immutable MessageIDs;</li><li>typed tool-call and tool-result messages;</li><li>exact branch lineage through ParentConversationID and ForkMessageID;</li><li>parent and child transcript isolation;</li><li>normal scoped-memory behaviour regardless of the originating Conversation;</li><li>Messaging and Work Intake ownership.</li></ul><h3 id="_3-identity-data-migration" tabindex="-1">3. Identity data migration <a class="header-anchor" href="#_3-identity-data-migration" aria-label="Permalink to &quot;3. Identity data migration&quot;">​</a></h3><p>The migration must define:</p><ul><li>the durable identity schema and repository implementation;</li><li>bootstrap of the permanent system identity;</li><li>stable IdentityIDs for existing configured Agents;</li><li>migration from configured identity names, empty-string ownership, and bot usernames;</li><li>preservation of historical attribution;</li><li>identity-aware uniqueness and transport deduplication;</li><li>correction of container and RPC capability resolution so execution uses the owning identity&#39;s bindings;</li><li>removal of identity-string equality from access-control behaviour.</li></ul><p>Exact schema and method signatures are implementation decisions. The approved Identity lifecycle and attribution semantics are fixed migration constraints.</p><h3 id="_4-workflow-migration" tabindex="-1">4. Workflow migration <a class="header-anchor" href="#_4-workflow-migration" aria-label="Permalink to &quot;4. Workflow migration&quot;">​</a></h3><p>The current implementation must be transformed deliberately:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>store.Task -&gt; WorkflowExecution</span></span>
<span class="line"><span>mutable Stage -&gt; StepExecution history</span></span>
<span class="line"><span>RetryCount / Attempt -&gt; Attempt records</span></span>
<span class="line"><span>workflow.Registry -&gt; versioned Workflow definitions</span></span>
<span class="line"><span>current stages -&gt; WorkflowStep definitions or Workflow plugins</span></span></code></pre></div><p>The migration must decide:</p><ul><li>Workflow definition and version persistence;</li><li>the smallest accepted-work-request contract consumed from Work Intake;</li><li>the enforced WorkflowExecution state machine;</li><li>atomic state and domain-event persistence;</li><li>migration of existing task rows and transition history;</li><li>disposition of current skill, Yaegi, and stage-plugin implementations;</li><li>the versioned worker-handoff contract;</li><li>scheduler, claim, retry, crash-recovery, and waiting-human cutover.</li></ul><p>Workflow remains a separate domain from Agent. A user or Agent may define or invoke a Workflow, but Workflow semantics and plugins remain Workflow-owned.</p><h3 id="_5-memory-placement-and-storage" tabindex="-1">5. Memory placement and storage <a class="header-anchor" href="#_5-memory-placement-and-storage" aria-label="Permalink to &quot;5. Memory placement and storage&quot;">​</a></h3><p>The four required scopes are fixed:</p><ul><li>global shared;</li><li>Agent-wide;</li><li>user-wide;</li><li>Agent-user relationship.</li></ul><p>A focused review of <code>internal/memory</code>, its providers, consumers, persistence, and tests must decide:</p><ul><li><code>internal/domain/memory</code> versus ownership within the Agent domain;</li><li>the authoritative memory record and revision model;</li><li>provider and infrastructure boundaries;</li><li>retrieval and access enforcement;</li><li>migration of existing memory data;</li><li>provenance representation.</li></ul><p>Conversation branches do not create another memory scope. A memory action has the same scoped effect regardless of which Conversation originated it.</p><h3 id="_6-runtime-and-process-boundaries" tabindex="-1">6. Runtime and process boundaries <a class="header-anchor" href="#_6-runtime-and-process-boundaries" aria-label="Permalink to &quot;6. Runtime and process boundaries&quot;">​</a></h3><p>The migration must decide which current execution paths survive:</p><ul><li>in-process execution;</li><li><code>archie-agent</code> subprocess execution;</li><li>NATS worker execution;</li><li>container isolation;</li><li>forge, store, and worktree RPC services.</li></ul><p>The source architecture remains a modular monolith. A retained process boundary requires a concrete security-isolation, failure-containment, scaling, or operational justification. Possible future extraction is insufficient.</p><h3 id="_7-shared-mechanics" tabindex="-1">7. Shared mechanics <a class="header-anchor" href="#_7-shared-mechanics" aria-label="Permalink to &quot;7. Shared mechanics&quot;">​</a></h3><p>The following cross-domain mechanics require exact contracts before dependent packages migrate:</p><ul><li>event-bus delivery and failure semantics;</li><li>policy evaluation API, composition, and precedence;</li><li>configuration candidate preparation, health validation, atomic promotion, observation, and rollback;</li><li>service-specific health, bounded remediation, isolation, and escalation;</li><li>changelog association and grouping.</li></ul><p>These shared mechanisms do not acquire ownership of domain meaning. Domains continue to own their commands, events, policies, settings, and consequences.</p><p>The copied Go <code>specgen</code> and VitePress documentation pipeline, output placement, developer commands, drift checking, hook sequence, and CI sequence are defined in <code>generated-documentation.md</code>. Adapting the copied files, implementing Archie&#39;s normalized documentation model and page renderers, and cutting <code>docs</code> over to its final location remain migration work rather than open product architecture.</p><h3 id="_8-cutover-sequence" tabindex="-1">8. Cutover sequence <a class="header-anchor" href="#_8-cutover-sequence" aria-label="Permalink to &quot;8. Cutover sequence&quot;">​</a></h3><p>The final migration plan must order:</p><ul><li>compatibility adapters;</li><li>schema migrations and data backfills;</li><li>any required dual-read or transitional paths;</li><li>domain-by-domain package replacement;</li><li>production wiring changes;</li><li>legacy package removal;</li><li>architecture tests preventing dependency regression;</li><li>focused, integration, race, and full quality gates.</li></ul><p>Each legacy package requires objective removal criteria. No compatibility path may become an indefinite second implementation.</p><h2 id="completion-criteria" tabindex="-1">Completion criteria <a class="header-anchor" href="#completion-criteria" aria-label="Permalink to &quot;Completion criteria&quot;">​</a></h2><p>Migration design is complete when:</p><ul><li>every current package has one approved owner and destination;</li><li>every mutable record has one authoritative owner and migration path;</li><li>all external and cross-process contracts have versioned owners;</li><li>existinLine truncated
<script>window.__VP_HASH_MAP__=JSON.parse("{\"architecture_agent-system.md\":\"Coj6mPZw\",\"architecture_configuration.md\":\"BsVGi7ja\",\"architecture_dependencies-and-contracts.md\":\"ByRODJZC\",\"architecture_generated-documentation.md\":\"qELen1k6\",\"architecture_identity.md\":\"CB0DkYo9\",\"architecture_index.md\":\"DJpk2YHf\",\"architecture_messaging-and-work-intake.md\":\"Q7MxXQDB\",\"architecture_migration-decisions.md\":\"oN2eGfag\",\"architecture_organisation.md\":\"mAPb3vCC\",\"architecture_package-review.md\":\"7BZCENBd\",\"architecture_plugins-and-extensions.md\":\"DmzsC2M0\",\"architecture_policy.md\":\"4L33IZiY\",\"architecture_safe-change-and-recovery.md\":\"CdYeF0XF\",\"archive_archie-core-architecture.md\":\"Bqg5-owD\",\"archive_archie-core-skills-prd-v2.md\":\"D3RVdXag\",\"archive_archie-core-skills-prd.md\":\"D1oUBHEN\",\"archive_decisions.md\":\"DkenJ6mD\",\"archive_design.md\":\"BwF1bH5l\",\"archive_prds_multi-agent-collaboration.md\":\"zqWXF3O0\",\"archive_prds_typescript-plugin-engine.md\":\"DBR1GKuy\",\"archive_prds_yaegi-plugin-system.md\":\"V36uzfZI\",\"index.md\":\"BdS51Ijr\",\"prds_01-project-management.md\":\"DEpuIAgg\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Archie\",\"description\":\"Documentation for the Archie personal agent platform.\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/favicon.svg\",\"nav\":[{\"text\":\"Architecture\",\"link\":\"/architecture/\"}],\"sidebar\":{\"/architecture/\":[{\"text\":\"Architecture\",\"items\":[{\"text\":\"Overview\",\"link\":\"/architecture/\"},{\"text\":\"Repository Organisation\",\"link\":\"/architecture/organisation\"},{\"text\":\"Dependencies and Contracts\",\"link\":\"/architecture/dependencies-and-contracts\"},{\"text\":\"Agent System\",\"link\":\"/architecture/agent-system\"},{\"text\":\"Configuration\",\"link\":\"/architecture/configuration\"},{\"text\":\"Identity\",\"link\":\"/architecture/identity\"},{\"text\":\"Messaging and Work Intake\",\"link\":\"/architecture/messaging-and-work-intake\"},{\"text\":\"Plugins and Extensions\",\"link\":\"/architecture/plugins-and-extensions\"},{\"text\":\"Policy System\",\"link\":\"/architecture/policy\"},{\"text\":\"Safe Change and Recovery\",\"link\":\"/architecture/safe-change-and-recovery\"},{\"text\":\"Generated Documentation\",\"link\":\"/architecture/generated-documentation\"},{\"text\":\"Domain and Feature Review Procedure\",\"link\":\"/architecture/package-review\"},{\"text\":\"Migration Decisions\",\"link\":\"/architecture/migration-decisions\"}]}]},\"search\":{\"provider\":\"local\"},\"footer\":{\"message\":\"Built with VitePress.\",\"copyright\":\"Archie\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
</body>
</html>
-55
View File
@@ -1,55 +0,0 @@
<!DOCTYPE html>
<html lang="en-US" dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Repository Organisation | Archie</title>
<meta name="description" content="Documentation for the Archie personal agent platform.">
<meta name="generator" content="VitePress v1.6.4">
<link rel="preload stylesheet" href="/assets/style.C4BXn3EN.css" as="style">
<link rel="preload stylesheet" href="/vp-icons.css" as="style">
<script type="module" src="/assets/app.HIbJYLU1.js"></script>
<link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="modulepreload" href="/assets/chunks/theme.B97NJxv0.js">
<link rel="modulepreload" href="/assets/chunks/framework.BWuWLRhz.js">
<link rel="modulepreload" href="/assets/architecture_organisation.md.mAPb3vCC.lean.js">
<link rel="icon" href="/favicon.svg">
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
</head>
<body>
<div id="app"><div class="Layout" data-v-cb931ff4><!--[--><!--]--><!--[--><span tabindex="-1" data-v-8ae66126></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-8ae66126>Skip to content</a><!--]--><!----><header class="VPNav" data-v-cb931ff4 data-v-a1925027><div class="VPNavBar" data-v-a1925027 data-v-2840085c><div class="wrapper" data-v-2840085c><div class="container" data-v-2840085c><div class="title" data-v-2840085c><div class="VPNavBarTitle has-sidebar" data-v-2840085c data-v-e7a29354><a class="title" href="/" data-v-e7a29354><!--[--><!--]--><!--[--><img class="VPImage logo" src="/favicon.svg" alt data-v-eec9b196><!--]--><span data-v-e7a29354>Archie</span><!--[--><!--]--></a></div></div><div class="content" data-v-2840085c><div class="content-body" data-v-2840085c><!--[--><!--]--><div class="VPNavBarSearch search" data-v-2840085c><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-2840085c data-v-ded89948><span id="main-nav-aria-label" class="visually-hidden" data-v-ded89948> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/architecture/" tabindex="0" data-v-ded89948 data-v-0a9a3d21><!--[--><span data-v-0a9a3d21>Architecture</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-2840085c data-v-4b074154><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-4b074154 data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-2840085c data-v-6ca47e2f data-v-b980f1c3><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-b980f1c3><span class="vpi-more-horizontal icon" data-v-b980f1c3></span></button><div class="menu" data-v-b980f1c3><div class="VPMenu" data-v-b980f1c3 data-v-a1767133><!----><!--[--><!--[--><!----><div class="group" data-v-6ca47e2f><div class="item appearance" data-v-6ca47e2f><p class="label" data-v-6ca47e2f>Appearance</p><div class="appearance-action" data-v-6ca47e2f><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-6ca47e2f data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-2840085c data-v-3597ebf2><span class="container" data-v-3597ebf2><span class="top" data-v-3597ebf2></span><span class="middle" data-v-3597ebf2></span><span class="bottom" data-v-3597ebf2></span></span></button></div></div></div></div><div class="divider" data-v-2840085c><div class="divider-line" data-v-2840085c></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-cb931ff4 data-v-c17e40bf><div class="container" data-v-c17e40bf><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-c17e40bf><span class="vpi-align-left menu-icon" data-v-c17e40bf></span><span class="menu-text" data-v-c17e40bf>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-c17e40bf data-v-88669269><button data-v-88669269>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-cb931ff4 data-v-f5090d1d><div class="curtain" data-v-f5090d1d></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-f5090d1d><span class="visually-hidden" id="sidebar-aria-label" data-v-f5090d1d> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-049afe89><section class="VPSidebarItem level-0 has-active" data-v-049afe89 data-v-ce191e9a><div class="item" role="button" tabindex="0" data-v-ce191e9a><div class="indicator" data-v-ce191e9a></div><h2 class="text" data-v-ce191e9a>Architecture</h2><!----></div><div class="items" data-v-ce191e9a><!--[--><div class="VPSidebarItem level-1 is-link" data-v-ce191e9a><div class="item" data-v-ce191e9a><div class="indicator" data-v-ce191e9a></div><a class="VPLink link link" href="/architecture/" data-v-ce19Line truncated
<span class="line"><span> archied/</span></span>
<span class="line"><span> archie-agent/</span></span>
<span class="line"><span></span></span>
<span class="line"><span>internal/</span></span>
<span class="line"><span> domain/</span></span>
<span class="line"><span> &lt;area&gt;/</span></span>
<span class="line"><span> eventbus/</span></span>
<span class="line"><span> policy/</span></span>
<span class="line"><span> infrastructure/</span></span>
<span class="line"><span> configuration/</span></span>
<span class="line"><span> eventbus/</span></span>
<span class="line"><span> nats/</span></span>
<span class="line"><span> forge/</span></span>
<span class="line"><span> persistence/</span></span>
<span class="line"><span> &lt;external-service&gt;/</span></span>
<span class="line"><span> app/</span></span>
<span class="line"><span> archied/</span></span>
<span class="line"><span> agentworker/</span></span>
<span class="line"><span></span></span>
<span class="line"><span>plugins/</span></span>
<span class="line"><span> &lt;plugin&gt;/</span></span>
<span class="line"><span>deployments/</span></span>
<span class="line"><span> &lt;supported-assembly&gt;/</span></span>
<span class="line"><span>docs/</span></span>
<span class="line"><span> guides/</span></span>
<span class="line"><span>examples/</span></span>
<span class="line"><span> &lt;copyable-example&gt;/</span></span>
<span class="line"><span>extras/</span></span>
<span class="line"><span> &lt;optional-extension&gt;/</span></span></code></pre></div><p>Domain names are chosen from application behaviour during package review. Existing names MUST NOT be retained merely to reduce migration work.</p><h2 id="domain-areas" tabindex="-1">Domain areas <a class="header-anchor" href="#domain-areas" aria-label="Permalink to &quot;Domain areas&quot;">​</a></h2><p>A domain owns one cohesive job performed by Archie. It contains that job&#39;s language, state, rules, operations, commands, events, policy implementations, runtime settings, and required service contracts.</p><p>Code that changes together SHOULD live together. Empty or ceremonial <code>entities</code>, <code>repositories</code>, or <code>services</code> layers are prohibited.</p><h2 id="application-composition" tabindex="-1">Application composition <a class="header-anchor" href="#application-composition" aria-label="Permalink to &quot;Application composition&quot;">​</a></h2><p><code>internal/app</code>:</p><ul><li>constructs domains and infrastructure implementations;</li><li>translates external configuration into domain and plugin settings;</li><li>connects commands, events, and shared contracts;</li><li>starts services in dependency order;</li><li>owns health aggregation and shutdown ordering.</li></ul><p><code>cmd/*</code> parses only process-level input and invokes the relevant application composition package. It MUST NOT contain substantive wiring or act as a service locator.</p><h2 id="process-boundaries" tabindex="-1">Process boundaries <a class="header-anchor" href="#process-boundaries" aria-label="Permalink to &quot;Process boundaries&quot;">​</a></h2><p>Archie begins as a modular monolith even when capabilities run in separate processes. A domain becomes a separately deployed service only for a concrete need such as security isolation, independent scaling, failure containment, or independent operation.</p><p>Possible future extraction does not justify premature network protocols or duplicated service scaffolding.</p><h2 id="optional-and-operational-material" tabindex="-1">Optional and operational material <a class="header-anchor" href="#optional-and-operational-material" aria-label="Permalink to &quot;Optional and operational material&quot;">​</a></h2><ul><li><code>extras/&lt;extension&gt;</code> contains a maintained optional extension with real behaviour. Core Archie MUST NOT import it, and removing <code>extras/</code> MUST NOT prevent the core application from building or running.</li><li><code>deployments/&lt;assembly&gt;</code> contains a supported assembly, including deployment definitions and concise operational instructions.</li><li><code>docs/guides/</code> contains handwritten explanation and links to generated reference material.</li><li><code>examples/</code> contains copyable samples with explicit purpose, prerequisites, and support expectations.</li></ul><p>Supported assemblies SHOULD demonstrate that capabilities can be selected independently.</p></div></div></main><footer class="VPDocFooter" data-v-81f89caf data-v-1e23d7de><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-1e23d7de><span class="visually-hidden" id="doc-footer-aria-label" data-v-1e23d7de>Pager</span><div class="pager" data-v-1e23d7de><a class="VPLink link pager-link prev" href="/architecture/" data-v-1e23d7de><!--[--><span class="desc" data-v-1e23d7de>Previous page</span><span class="title" data-v-1e23d7de>Overview</span><!--]--></a></div><div class="pager" data-v-1e23d7de><a class="VPLink link pager-link next" href="/architecture/dependencies-and-contracts" data-v-1e23d7de><!--[--><span class="desc" data-v-1e23d7de>Next page</span><span class="title" data-v-1e23d7de>Dependencies and Contracts</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><footer class="VPFooter has-sidebar" data-v-cb931ff4 data-v-c113a85a><div class="container" data-v-c113a85a><p class="message" data-v-c113a85a>Built with VitePress.</p><p class="copyright" data-v-c113a85a>Archie</p></div></footer><!--[--><!--]--></div></div>
<script>window.__VP_HASH_MAP__=JSON.parse("{\"architecture_agent-system.md\":\"Coj6mPZw\",\"architecture_configuration.md\":\"BsVGi7ja\",\"architecture_dependencies-and-contracts.md\":\"ByRODJZC\",\"architecture_generated-documentation.md\":\"qELen1k6\",\"architecture_identity.md\":\"CB0DkYo9\",\"architecture_index.md\":\"DJpk2YHf\",\"architecture_messaging-and-work-intake.md\":\"Q7MxXQDB\",\"architecture_migration-decisions.md\":\"oN2eGfag\",\"architecture_organisation.md\":\"mAPb3vCC\",\"architecture_package-review.md\":\"7BZCENBd\",\"architecture_plugins-and-extensions.md\":\"DmzsC2M0\",\"architecture_policy.md\":\"4L33IZiY\",\"architecture_safe-change-and-recovery.md\":\"CdYeF0XF\",\"archive_archie-core-architecture.md\":\"Bqg5-owD\",\"archive_archie-core-skills-prd-v2.md\":\"D3RVdXag\",\"archive_archie-core-skills-prd.md\":\"D1oUBHEN\",\"archive_decisions.md\":\"DkenJ6mD\",\"archive_design.md\":\"BwF1bH5l\",\"archive_prds_multi-agent-collaboration.md\":\"zqWXF3O0\",\"archive_prds_typescript-plugin-engine.md\":\"DBR1GKuy\",\"archive_prds_yaegi-plugin-system.md\":\"V36uzfZI\",\"index.md\":\"BdS51Ijr\",\"prds_01-project-management.md\":\"DEpuIAgg\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Archie\",\"description\":\"Documentation for the Archie personal agent platform.\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/favicon.svg\",\"nav\":[{\"text\":\"Architecture\",\"link\":\"/architecture/\"}],\"sidebar\":{\"/architecture/\":[{\"text\":\"Architecture\",\"items\":[{\"text\":\"Overview\",\"link\":\"/architecture/\"},{\"text\":\"Repository Organisation\",\"link\":\"/architecture/organisation\"},{\"text\":\"Dependencies and Contracts\",\"link\":\"/architecture/dependencies-and-contracts\"},{\"text\":\"Agent System\",\"link\":\"/architecture/agent-system\"},{\"text\":\"Configuration\",\"link\":\"/architecture/configuration\"},{\"text\":\"Identity\",\"link\":\"/architecture/identity\"},{\"text\":\"Messaging and Work Intake\",\"link\":\"/architecture/messaging-and-work-intake\"},{\"text\":\"Plugins and Extensions\",\"link\":\"/architecture/plugins-and-extensions\"},{\"text\":\"Policy System\",\"link\":\"/architecture/policy\"},{\"text\":\"Safe Change and Recovery\",\"link\":\"/architecture/safe-change-and-recovery\"},{\"text\":\"Generated Documentation\",\"link\":\"/architecture/generated-documentation\"},{\"text\":\"Domain and Feature Review Procedure\",\"link\":\"/architecture/package-review\"},{\"text\":\"Migration Decisions\",\"link\":\"/architecture/migration-decisions\"}]}]},\"search\":{\"provider\":\"local\"},\"footer\":{\"message\":\"Built with VitePress.\",\"copyright\":\"Archie\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
</body>
</html>
-26
View File
@@ -1,26 +0,0 @@
<!DOCTYPE html>
<html lang="en-US" dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Domain and Feature Review Procedure | Archie</title>
<meta name="description" content="Documentation for the Archie personal agent platform.">
<meta name="generator" content="VitePress v1.6.4">
<link rel="preload stylesheet" href="/assets/style.C4BXn3EN.css" as="style">
<link rel="preload stylesheet" href="/vp-icons.css" as="style">
<script type="module" src="/assets/app.HIbJYLU1.js"></script>
<link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="modulepreload" href="/assets/chunks/theme.B97NJxv0.js">
<link rel="modulepreload" href="/assets/chunks/framework.BWuWLRhz.js">
<link rel="modulepreload" href="/assets/architecture_package-review.md.7BZCENBd.lean.js">
<link rel="icon" href="/favicon.svg">
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
</head>
<body>
<div id="app"><div class="Layout" data-v-cb931ff4><!--[--><!--]--><!--[--><span tabindex="-1" data-v-8ae66126></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-8ae66126>Skip to content</a><!--]--><!----><header class="VPNav" data-v-cb931ff4 data-v-a1925027><div class="VPNavBar" data-v-a1925027 data-v-2840085c><div class="wrapper" data-v-2840085c><div class="container" data-v-2840085c><div class="title" data-v-2840085c><div class="VPNavBarTitle has-sidebar" data-v-2840085c data-v-e7a29354><a class="title" href="/" data-v-e7a29354><!--[--><!--]--><!--[--><img class="VPImage logo" src="/favicon.svg" alt data-v-eec9b196><!--]--><span data-v-e7a29354>Archie</span><!--[--><!--]--></a></div></div><div class="content" data-v-2840085c><div class="content-body" data-v-2840085c><!--[--><!--]--><div class="VPNavBarSearch search" data-v-2840085c><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-2840085c data-v-ded89948><span id="main-nav-aria-label" class="visually-hidden" data-v-ded89948> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/architecture/" tabindex="0" data-v-ded89948 data-v-0a9a3d21><!--[--><span data-v-0a9a3d21>Architecture</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-2840085c data-v-4b074154><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-4b074154 data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-2840085c data-v-6ca47e2f data-v-b980f1c3><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-b980f1c3><span class="vpi-more-horizontal icon" data-v-b980f1c3></span></button><div class="menu" data-v-b980f1c3><div class="VPMenu" data-v-b980f1c3 data-v-a1767133><!----><!--[--><!--[--><!----><div class="group" data-v-6ca47e2f><div class="item appearance" data-v-6ca47e2f><p class="label" data-v-6ca47e2f>Appearance</p><div class="appearance-action" data-v-6ca47e2f><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-6ca47e2f data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-2840085c data-v-3597ebf2><span class="container" data-v-3597ebf2><span class="top" data-v-3597ebf2></span><span class="middle" data-v-3597ebf2></span><span class="bottom" data-v-3597ebf2></span></span></button></div></div></div></div><div class="divider" data-v-2840085c><div class="divider-line" data-v-2840085c></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-cb931ff4 data-v-c17e40bf><div class="container" data-v-c17e40bf><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-c17e40bf><span class="vpi-align-left menu-icon" data-v-c17e40bf></span><span class="menu-text" data-v-c17e40bf>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-c17e40bf data-v-88669269><button data-v-88669269>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-cb931ff4 data-v-f5090d1d><div class="curtain" data-v-f5090d1d></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-f5090d1d><span class="visually-hidden" id="sidebar-aria-label" data-v-f5090d1d> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-049afe89><section class="VPSidebarItem level-0 has-active" data-v-049afe89 data-v-ce191e9a><div class="item" role="button" tabindex="0" data-v-ce191e9a><div class="indicator" data-v-ce191e9a></div><h2 class="text" data-v-ce191e9a>Architecture</h2><!----></div><div class="items" data-v-ce191e9a><!--[--><div class="VPSidebarItem level-1 is-link" data-v-ce191e9a><div class="item" data-v-ce191e9a><div class="indicator" data-v-ce191e9a></div><a class="VPLink link link" href="/architecture/" data-v-ce19Line truncated
<script>window.__VP_HASH_MAP__=JSON.parse("{\"architecture_agent-system.md\":\"Coj6mPZw\",\"architecture_configuration.md\":\"BsVGi7ja\",\"architecture_dependencies-and-contracts.md\":\"ByRODJZC\",\"architecture_generated-documentation.md\":\"qELen1k6\",\"architecture_identity.md\":\"CB0DkYo9\",\"architecture_index.md\":\"DJpk2YHf\",\"architecture_messaging-and-work-intake.md\":\"Q7MxXQDB\",\"architecture_migration-decisions.md\":\"oN2eGfag\",\"architecture_organisation.md\":\"mAPb3vCC\",\"architecture_package-review.md\":\"7BZCENBd\",\"architecture_plugins-and-extensions.md\":\"DmzsC2M0\",\"architecture_policy.md\":\"4L33IZiY\",\"architecture_safe-change-and-recovery.md\":\"CdYeF0XF\",\"archive_archie-core-architecture.md\":\"Bqg5-owD\",\"archive_archie-core-skills-prd-v2.md\":\"D3RVdXag\",\"archive_archie-core-skills-prd.md\":\"D1oUBHEN\",\"archive_decisions.md\":\"DkenJ6mD\",\"archive_design.md\":\"BwF1bH5l\",\"archive_prds_multi-agent-collaboration.md\":\"zqWXF3O0\",\"archive_prds_typescript-plugin-engine.md\":\"DBR1GKuy\",\"archive_prds_yaegi-plugin-system.md\":\"V36uzfZI\",\"index.md\":\"BdS51Ijr\",\"prds_01-project-management.md\":\"DEpuIAgg\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Archie\",\"description\":\"Documentation for the Archie personal agent platform.\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/favicon.svg\",\"nav\":[{\"text\":\"Architecture\",\"link\":\"/architecture/\"}],\"sidebar\":{\"/architecture/\":[{\"text\":\"Architecture\",\"items\":[{\"text\":\"Overview\",\"link\":\"/architecture/\"},{\"text\":\"Repository Organisation\",\"link\":\"/architecture/organisation\"},{\"text\":\"Dependencies and Contracts\",\"link\":\"/architecture/dependencies-and-contracts\"},{\"text\":\"Agent System\",\"link\":\"/architecture/agent-system\"},{\"text\":\"Configuration\",\"link\":\"/architecture/configuration\"},{\"text\":\"Identity\",\"link\":\"/architecture/identity\"},{\"text\":\"Messaging and Work Intake\",\"link\":\"/architecture/messaging-and-work-intake\"},{\"text\":\"Plugins and Extensions\",\"link\":\"/architecture/plugins-and-extensions\"},{\"text\":\"Policy System\",\"link\":\"/architecture/policy\"},{\"text\":\"Safe Change and Recovery\",\"link\":\"/architecture/safe-change-and-recovery\"},{\"text\":\"Generated Documentation\",\"link\":\"/architecture/generated-documentation\"},{\"text\":\"Domain and Feature Review Procedure\",\"link\":\"/architecture/package-review\"},{\"text\":\"Migration Decisions\",\"link\":\"/architecture/migration-decisions\"}]}]},\"search\":{\"provider\":\"local\"},\"footer\":{\"message\":\"Built with VitePress.\",\"copyright\":\"Archie\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
</body>
</html>
@@ -1,26 +0,0 @@
<!DOCTYPE html>
<html lang="en-US" dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Plugins and Extensions | Archie</title>
<meta name="description" content="Documentation for the Archie personal agent platform.">
<meta name="generator" content="VitePress v1.6.4">
<link rel="preload stylesheet" href="/assets/style.C4BXn3EN.css" as="style">
<link rel="preload stylesheet" href="/vp-icons.css" as="style">
<script type="module" src="/assets/app.HIbJYLU1.js"></script>
<link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="modulepreload" href="/assets/chunks/theme.B97NJxv0.js">
<link rel="modulepreload" href="/assets/chunks/framework.BWuWLRhz.js">
<link rel="modulepreload" href="/assets/architecture_plugins-and-extensions.md.DmzsC2M0.lean.js">
<link rel="icon" href="/favicon.svg">
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
</head>
<body>
<div id="app"><div class="Layout" data-v-cb931ff4><!--[--><!--]--><!--[--><span tabindex="-1" data-v-8ae66126></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-8ae66126>Skip to content</a><!--]--><!----><header class="VPNav" data-v-cb931ff4 data-v-a1925027><div class="VPNavBar" data-v-a1925027 data-v-2840085c><div class="wrapper" data-v-2840085c><div class="container" data-v-2840085c><div class="title" data-v-2840085c><div class="VPNavBarTitle has-sidebar" data-v-2840085c data-v-e7a29354><a class="title" href="/" data-v-e7a29354><!--[--><!--]--><!--[--><img class="VPImage logo" src="/favicon.svg" alt data-v-eec9b196><!--]--><span data-v-e7a29354>Archie</span><!--[--><!--]--></a></div></div><div class="content" data-v-2840085c><div class="content-body" data-v-2840085c><!--[--><!--]--><div class="VPNavBarSearch search" data-v-2840085c><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-2840085c data-v-ded89948><span id="main-nav-aria-label" class="visually-hidden" data-v-ded89948> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/architecture/" tabindex="0" data-v-ded89948 data-v-0a9a3d21><!--[--><span data-v-0a9a3d21>Architecture</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-2840085c data-v-4b074154><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-4b074154 data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-2840085c data-v-6ca47e2f data-v-b980f1c3><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-b980f1c3><span class="vpi-more-horizontal icon" data-v-b980f1c3></span></button><div class="menu" data-v-b980f1c3><div class="VPMenu" data-v-b980f1c3 data-v-a1767133><!----><!--[--><!--[--><!----><div class="group" data-v-6ca47e2f><div class="item appearance" data-v-6ca47e2f><p class="label" data-v-6ca47e2f>Appearance</p><div class="appearance-action" data-v-6ca47e2f><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-6ca47e2f data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-2840085c data-v-3597ebf2><span class="container" data-v-3597ebf2><span class="top" data-v-3597ebf2></span><span class="middle" data-v-3597ebf2></span><span class="bottom" data-v-3597ebf2></span></span></button></div></div></div></div><div class="divider" data-v-2840085c><div class="divider-line" data-v-2840085c></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-cb931ff4 data-v-c17e40bf><div class="container" data-v-c17e40bf><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-c17e40bf><span class="vpi-align-left menu-icon" data-v-c17e40bf></span><span class="menu-text" data-v-c17e40bf>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-c17e40bf data-v-88669269><button data-v-88669269>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-cb931ff4 data-v-f5090d1d><div class="curtain" data-v-f5090d1d></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-f5090d1d><span class="visually-hidden" id="sidebar-aria-label" data-v-f5090d1d> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-049afe89><section class="VPSidebarItem level-0 has-active" data-v-049afe89 data-v-ce191e9a><div class="item" role="button" tabindex="0" data-v-ce191e9a><div class="indicator" data-v-ce191e9a></div><h2 class="text" data-v-ce191e9a>Architecture</h2><!----></div><div class="items" data-v-ce191e9a><!--[--><div class="VPSidebarItem level-1 is-link" data-v-ce191e9a><div class="item" data-v-ce191e9a><div class="indicator" data-v-ce191e9a></div><a class="VPLink link link" href="/architecture/" data-v-ce19Line truncated
<script>window.__VP_HASH_MAP__=JSON.parse("{\"architecture_agent-system.md\":\"Coj6mPZw\",\"architecture_configuration.md\":\"BsVGi7ja\",\"architecture_dependencies-and-contracts.md\":\"ByRODJZC\",\"architecture_generated-documentation.md\":\"qELen1k6\",\"architecture_identity.md\":\"CB0DkYo9\",\"architecture_index.md\":\"DJpk2YHf\",\"architecture_messaging-and-work-intake.md\":\"Q7MxXQDB\",\"architecture_migration-decisions.md\":\"oN2eGfag\",\"architecture_organisation.md\":\"mAPb3vCC\",\"architecture_package-review.md\":\"7BZCENBd\",\"architecture_plugins-and-extensions.md\":\"DmzsC2M0\",\"architecture_policy.md\":\"4L33IZiY\",\"architecture_safe-change-and-recovery.md\":\"CdYeF0XF\",\"archive_archie-core-architecture.md\":\"Bqg5-owD\",\"archive_archie-core-skills-prd-v2.md\":\"D3RVdXag\",\"archive_archie-core-skills-prd.md\":\"D1oUBHEN\",\"archive_decisions.md\":\"DkenJ6mD\",\"archive_design.md\":\"BwF1bH5l\",\"archive_prds_multi-agent-collaboration.md\":\"zqWXF3O0\",\"archive_prds_typescript-plugin-engine.md\":\"DBR1GKuy\",\"archive_prds_yaegi-plugin-system.md\":\"V36uzfZI\",\"index.md\":\"BdS51Ijr\",\"prds_01-project-management.md\":\"DEpuIAgg\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Archie\",\"description\":\"Documentation for the Archie personal agent platform.\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/favicon.svg\",\"nav\":[{\"text\":\"Architecture\",\"link\":\"/architecture/\"}],\"sidebar\":{\"/architecture/\":[{\"text\":\"Architecture\",\"items\":[{\"text\":\"Overview\",\"link\":\"/architecture/\"},{\"text\":\"Repository Organisation\",\"link\":\"/architecture/organisation\"},{\"text\":\"Dependencies and Contracts\",\"link\":\"/architecture/dependencies-and-contracts\"},{\"text\":\"Agent System\",\"link\":\"/architecture/agent-system\"},{\"text\":\"Configuration\",\"link\":\"/architecture/configuration\"},{\"text\":\"Identity\",\"link\":\"/architecture/identity\"},{\"text\":\"Messaging and Work Intake\",\"link\":\"/architecture/messaging-and-work-intake\"},{\"text\":\"Plugins and Extensions\",\"link\":\"/architecture/plugins-and-extensions\"},{\"text\":\"Policy System\",\"link\":\"/architecture/policy\"},{\"text\":\"Safe Change and Recovery\",\"link\":\"/architecture/safe-change-and-recovery\"},{\"text\":\"Generated Documentation\",\"link\":\"/architecture/generated-documentation\"},{\"text\":\"Domain and Feature Review Procedure\",\"link\":\"/architecture/package-review\"},{\"text\":\"Migration Decisions\",\"link\":\"/architecture/migration-decisions\"}]}]},\"search\":{\"provider\":\"local\"},\"footer\":{\"message\":\"Built with VitePress.\",\"copyright\":\"Archie\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
</body>
</html>
-26
View File
@@ -1,26 +0,0 @@
<!DOCTYPE html>
<html lang="en-US" dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Policy System | Archie</title>
<meta name="description" content="Documentation for the Archie personal agent platform.">
<meta name="generator" content="VitePress v1.6.4">
<link rel="preload stylesheet" href="/assets/style.C4BXn3EN.css" as="style">
<link rel="preload stylesheet" href="/vp-icons.css" as="style">
<script type="module" src="/assets/app.HIbJYLU1.js"></script>
<link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="modulepreload" href="/assets/chunks/theme.B97NJxv0.js">
<link rel="modulepreload" href="/assets/chunks/framework.BWuWLRhz.js">
<link rel="modulepreload" href="/assets/architecture_policy.md.4L33IZiY.lean.js">
<link rel="icon" href="/favicon.svg">
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
</head>
<body>
<div id="app"><div class="Layout" data-v-cb931ff4><!--[--><!--]--><!--[--><span tabindex="-1" data-v-8ae66126></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-8ae66126>Skip to content</a><!--]--><!----><header class="VPNav" data-v-cb931ff4 data-v-a1925027><div class="VPNavBar" data-v-a1925027 data-v-2840085c><div class="wrapper" data-v-2840085c><div class="container" data-v-2840085c><div class="title" data-v-2840085c><div class="VPNavBarTitle has-sidebar" data-v-2840085c data-v-e7a29354><a class="title" href="/" data-v-e7a29354><!--[--><!--]--><!--[--><img class="VPImage logo" src="/favicon.svg" alt data-v-eec9b196><!--]--><span data-v-e7a29354>Archie</span><!--[--><!--]--></a></div></div><div class="content" data-v-2840085c><div class="content-body" data-v-2840085c><!--[--><!--]--><div class="VPNavBarSearch search" data-v-2840085c><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-2840085c data-v-ded89948><span id="main-nav-aria-label" class="visually-hidden" data-v-ded89948> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/architecture/" tabindex="0" data-v-ded89948 data-v-0a9a3d21><!--[--><span data-v-0a9a3d21>Architecture</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-2840085c data-v-4b074154><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-4b074154 data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-2840085c data-v-6ca47e2f data-v-b980f1c3><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-b980f1c3><span class="vpi-more-horizontal icon" data-v-b980f1c3></span></button><div class="menu" data-v-b980f1c3><div class="VPMenu" data-v-b980f1c3 data-v-a1767133><!----><!--[--><!--[--><!----><div class="group" data-v-6ca47e2f><div class="item appearance" data-v-6ca47e2f><p class="label" data-v-6ca47e2f>Appearance</p><div class="appearance-action" data-v-6ca47e2f><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-6ca47e2f data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-2840085c data-v-3597ebf2><span class="container" data-v-3597ebf2><span class="top" data-v-3597ebf2></span><span class="middle" data-v-3597ebf2></span><span class="bottom" data-v-3597ebf2></span></span></button></div></div></div></div><div class="divider" data-v-2840085c><div class="divider-line" data-v-2840085c></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-cb931ff4 data-v-c17e40bf><div class="container" data-v-c17e40bf><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-c17e40bf><span class="vpi-align-left menu-icon" data-v-c17e40bf></span><span class="menu-text" data-v-c17e40bf>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-c17e40bf data-v-88669269><button data-v-88669269>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-cb931ff4 data-v-f5090d1d><div class="curtain" data-v-f5090d1d></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-f5090d1d><span class="visually-hidden" id="sidebar-aria-label" data-v-f5090d1d> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-049afe89><section class="VPSidebarItem level-0 has-active" data-v-049afe89 data-v-ce191e9a><div class="item" role="button" tabindex="0" data-v-ce191e9a><div class="indicator" data-v-ce191e9a></div><h2 class="text" data-v-ce191e9a>Architecture</h2><!----></div><div class="items" data-v-ce191e9a><!--[--><div class="VPSidebarItem level-1 is-link" data-v-ce191e9a><div class="item" data-v-ce191e9a><div class="indicator" data-v-ce191e9a></div><a class="VPLink link link" href="/architecture/" data-v-ce19Line truncated
<script>window.__VP_HASH_MAP__=JSON.parse("{\"architecture_agent-system.md\":\"Coj6mPZw\",\"architecture_configuration.md\":\"BsVGi7ja\",\"architecture_dependencies-and-contracts.md\":\"ByRODJZC\",\"architecture_generated-documentation.md\":\"qELen1k6\",\"architecture_identity.md\":\"CB0DkYo9\",\"architecture_index.md\":\"DJpk2YHf\",\"architecture_messaging-and-work-intake.md\":\"Q7MxXQDB\",\"architecture_migration-decisions.md\":\"oN2eGfag\",\"architecture_organisation.md\":\"mAPb3vCC\",\"architecture_package-review.md\":\"7BZCENBd\",\"architecture_plugins-and-extensions.md\":\"DmzsC2M0\",\"architecture_policy.md\":\"4L33IZiY\",\"architecture_safe-change-and-recovery.md\":\"CdYeF0XF\",\"archive_archie-core-architecture.md\":\"Bqg5-owD\",\"archive_archie-core-skills-prd-v2.md\":\"D3RVdXag\",\"archive_archie-core-skills-prd.md\":\"D1oUBHEN\",\"archive_decisions.md\":\"DkenJ6mD\",\"archive_design.md\":\"BwF1bH5l\",\"archive_prds_multi-agent-collaboration.md\":\"zqWXF3O0\",\"archive_prds_typescript-plugin-engine.md\":\"DBR1GKuy\",\"archive_prds_yaegi-plugin-system.md\":\"V36uzfZI\",\"index.md\":\"BdS51Ijr\",\"prds_01-project-management.md\":\"DEpuIAgg\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Archie\",\"description\":\"Documentation for the Archie personal agent platform.\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/favicon.svg\",\"nav\":[{\"text\":\"Architecture\",\"link\":\"/architecture/\"}],\"sidebar\":{\"/architecture/\":[{\"text\":\"Architecture\",\"items\":[{\"text\":\"Overview\",\"link\":\"/architecture/\"},{\"text\":\"Repository Organisation\",\"link\":\"/architecture/organisation\"},{\"text\":\"Dependencies and Contracts\",\"link\":\"/architecture/dependencies-and-contracts\"},{\"text\":\"Agent System\",\"link\":\"/architecture/agent-system\"},{\"text\":\"Configuration\",\"link\":\"/architecture/configuration\"},{\"text\":\"Identity\",\"link\":\"/architecture/identity\"},{\"text\":\"Messaging and Work Intake\",\"link\":\"/architecture/messaging-and-work-intake\"},{\"text\":\"Plugins and Extensions\",\"link\":\"/architecture/plugins-and-extensions\"},{\"text\":\"Policy System\",\"link\":\"/architecture/policy\"},{\"text\":\"Safe Change and Recovery\",\"link\":\"/architecture/safe-change-and-recovery\"},{\"text\":\"Generated Documentation\",\"link\":\"/architecture/generated-documentation\"},{\"text\":\"Domain and Feature Review Procedure\",\"link\":\"/architecture/package-review\"},{\"text\":\"Migration Decisions\",\"link\":\"/architecture/migration-decisions\"}]}]},\"search\":{\"provider\":\"local\"},\"footer\":{\"message\":\"Built with VitePress.\",\"copyright\":\"Archie\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
</body>
</html>
@@ -1,26 +0,0 @@
<!DOCTYPE html>
<html lang="en-US" dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Safe Change and Recovery | Archie</title>
<meta name="description" content="Documentation for the Archie personal agent platform.">
<meta name="generator" content="VitePress v1.6.4">
<link rel="preload stylesheet" href="/assets/style.C4BXn3EN.css" as="style">
<link rel="preload stylesheet" href="/vp-icons.css" as="style">
<script type="module" src="/assets/app.HIbJYLU1.js"></script>
<link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="modulepreload" href="/assets/chunks/theme.B97NJxv0.js">
<link rel="modulepreload" href="/assets/chunks/framework.BWuWLRhz.js">
<link rel="modulepreload" href="/assets/architecture_safe-change-and-recovery.md.CdYeF0XF.lean.js">
<link rel="icon" href="/favicon.svg">
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
</head>
<body>
<div id="app"><div class="Layout" data-v-cb931ff4><!--[--><!--]--><!--[--><span tabindex="-1" data-v-8ae66126></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-8ae66126>Skip to content</a><!--]--><!----><header class="VPNav" data-v-cb931ff4 data-v-a1925027><div class="VPNavBar" data-v-a1925027 data-v-2840085c><div class="wrapper" data-v-2840085c><div class="container" data-v-2840085c><div class="title" data-v-2840085c><div class="VPNavBarTitle has-sidebar" data-v-2840085c data-v-e7a29354><a class="title" href="/" data-v-e7a29354><!--[--><!--]--><!--[--><img class="VPImage logo" src="/favicon.svg" alt data-v-eec9b196><!--]--><span data-v-e7a29354>Archie</span><!--[--><!--]--></a></div></div><div class="content" data-v-2840085c><div class="content-body" data-v-2840085c><!--[--><!--]--><div class="VPNavBarSearch search" data-v-2840085c><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-2840085c data-v-ded89948><span id="main-nav-aria-label" class="visually-hidden" data-v-ded89948> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/architecture/" tabindex="0" data-v-ded89948 data-v-0a9a3d21><!--[--><span data-v-0a9a3d21>Architecture</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-2840085c data-v-4b074154><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-4b074154 data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-2840085c data-v-6ca47e2f data-v-b980f1c3><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-b980f1c3><span class="vpi-more-horizontal icon" data-v-b980f1c3></span></button><div class="menu" data-v-b980f1c3><div class="VPMenu" data-v-b980f1c3 data-v-a1767133><!----><!--[--><!--[--><!----><div class="group" data-v-6ca47e2f><div class="item appearance" data-v-6ca47e2f><p class="label" data-v-6ca47e2f>Appearance</p><div class="appearance-action" data-v-6ca47e2f><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-6ca47e2f data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-2840085c data-v-3597ebf2><span class="container" data-v-3597ebf2><span class="top" data-v-3597ebf2></span><span class="middle" data-v-3597ebf2></span><span class="bottom" data-v-3597ebf2></span></span></button></div></div></div></div><div class="divider" data-v-2840085c><div class="divider-line" data-v-2840085c></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-cb931ff4 data-v-c17e40bf><div class="container" data-v-c17e40bf><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-c17e40bf><span class="vpi-align-left menu-icon" data-v-c17e40bf></span><span class="menu-text" data-v-c17e40bf>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-c17e40bf data-v-88669269><button data-v-88669269>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-cb931ff4 data-v-f5090d1d><div class="curtain" data-v-f5090d1d></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-f5090d1d><span class="visually-hidden" id="sidebar-aria-label" data-v-f5090d1d> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-049afe89><section class="VPSidebarItem level-0 has-active" data-v-049afe89 data-v-ce191e9a><div class="item" role="button" tabindex="0" data-v-ce191e9a><div class="indicator" data-v-ce191e9a></div><h2 class="text" data-v-ce191e9a>Architecture</h2><!----></div><div class="items" data-v-ce191e9a><!--[--><div class="VPSidebarItem level-1 is-link" data-v-ce191e9a><div class="item" data-v-ce191e9a><div class="indicator" data-v-ce191e9a></div><a class="VPLink link link" href="/architecture/" data-v-ce19Line truncated
<script>window.__VP_HASH_MAP__=JSON.parse("{\"architecture_agent-system.md\":\"Coj6mPZw\",\"architecture_configuration.md\":\"BsVGi7ja\",\"architecture_dependencies-and-contracts.md\":\"ByRODJZC\",\"architecture_generated-documentation.md\":\"qELen1k6\",\"architecture_identity.md\":\"CB0DkYo9\",\"architecture_index.md\":\"DJpk2YHf\",\"architecture_messaging-and-work-intake.md\":\"Q7MxXQDB\",\"architecture_migration-decisions.md\":\"oN2eGfag\",\"architecture_organisation.md\":\"mAPb3vCC\",\"architecture_package-review.md\":\"7BZCENBd\",\"architecture_plugins-and-extensions.md\":\"DmzsC2M0\",\"architecture_policy.md\":\"4L33IZiY\",\"architecture_safe-change-and-recovery.md\":\"CdYeF0XF\",\"archive_archie-core-architecture.md\":\"Bqg5-owD\",\"archive_archie-core-skills-prd-v2.md\":\"D3RVdXag\",\"archive_archie-core-skills-prd.md\":\"D1oUBHEN\",\"archive_decisions.md\":\"DkenJ6mD\",\"archive_design.md\":\"BwF1bH5l\",\"archive_prds_multi-agent-collaboration.md\":\"zqWXF3O0\",\"archive_prds_typescript-plugin-engine.md\":\"DBR1GKuy\",\"archive_prds_yaegi-plugin-system.md\":\"V36uzfZI\",\"index.md\":\"BdS51Ijr\",\"prds_01-project-management.md\":\"DEpuIAgg\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Archie\",\"description\":\"Documentation for the Archie personal agent platform.\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/favicon.svg\",\"nav\":[{\"text\":\"Architecture\",\"link\":\"/architecture/\"}],\"sidebar\":{\"/architecture/\":[{\"text\":\"Architecture\",\"items\":[{\"text\":\"Overview\",\"link\":\"/architecture/\"},{\"text\":\"Repository Organisation\",\"link\":\"/architecture/organisation\"},{\"text\":\"Dependencies and Contracts\",\"link\":\"/architecture/dependencies-and-contracts\"},{\"text\":\"Agent System\",\"link\":\"/architecture/agent-system\"},{\"text\":\"Configuration\",\"link\":\"/architecture/configuration\"},{\"text\":\"Identity\",\"link\":\"/architecture/identity\"},{\"text\":\"Messaging and Work Intake\",\"link\":\"/architecture/messaging-and-work-intake\"},{\"text\":\"Plugins and Extensions\",\"link\":\"/architecture/plugins-and-extensions\"},{\"text\":\"Policy System\",\"link\":\"/architecture/policy\"},{\"text\":\"Safe Change and Recovery\",\"link\":\"/architecture/safe-change-and-recovery\"},{\"text\":\"Generated Documentation\",\"link\":\"/architecture/generated-documentation\"},{\"text\":\"Domain and Feature Review Procedure\",\"link\":\"/architecture/package-review\"},{\"text\":\"Migration Decisions\",\"link\":\"/architecture/migration-decisions\"}]}]},\"search\":{\"provider\":\"local\"},\"footer\":{\"message\":\"Built with VitePress.\",\"copyright\":\"Archie\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
</body>
</html>
-26
View File
@@ -1,26 +0,0 @@
<!DOCTYPE html>
<html lang="en-US" dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>archied -- design notes | Archie</title>
<meta name="description" content="Documentation for the Archie personal agent platform.">
<meta name="generator" content="VitePress v1.6.4">
<link rel="preload stylesheet" href="/assets/style.C4BXn3EN.css" as="style">
<link rel="preload stylesheet" href="/vp-icons.css" as="style">
<script type="module" src="/assets/app.HIbJYLU1.js"></script>
<link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="modulepreload" href="/assets/chunks/theme.B97NJxv0.js">
<link rel="modulepreload" href="/assets/chunks/framework.BWuWLRhz.js">
<link rel="modulepreload" href="/assets/archive_DESIGN.md.BwF1bH5l.lean.js">
<link rel="icon" href="/favicon.svg">
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
</head>
<body>
<div id="app"><div class="Layout" data-v-cb931ff4><!--[--><!--]--><!--[--><span tabindex="-1" data-v-8ae66126></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-8ae66126>Skip to content</a><!--]--><!----><header class="VPNav" data-v-cb931ff4 data-v-a1925027><div class="VPNavBar" data-v-a1925027 data-v-2840085c><div class="wrapper" data-v-2840085c><div class="container" data-v-2840085c><div class="title" data-v-2840085c><div class="VPNavBarTitle" data-v-2840085c data-v-e7a29354><a class="title" href="/" data-v-e7a29354><!--[--><!--]--><!--[--><img class="VPImage logo" src="/favicon.svg" alt data-v-eec9b196><!--]--><span data-v-e7a29354>Archie</span><!--[--><!--]--></a></div></div><div class="content" data-v-2840085c><div class="content-body" data-v-2840085c><!--[--><!--]--><div class="VPNavBarSearch search" data-v-2840085c><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-2840085c data-v-ded89948><span id="main-nav-aria-label" class="visually-hidden" data-v-ded89948> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/architecture/" tabindex="0" data-v-ded89948 data-v-0a9a3d21><!--[--><span data-v-0a9a3d21>Architecture</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-2840085c data-v-4b074154><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-4b074154 data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-2840085c data-v-6ca47e2f data-v-b980f1c3><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-b980f1c3><span class="vpi-more-horizontal icon" data-v-b980f1c3></span></button><div class="menu" data-v-b980f1c3><div class="VPMenu" data-v-b980f1c3 data-v-a1767133><!----><!--[--><!--[--><!----><div class="group" data-v-6ca47e2f><div class="item appearance" data-v-6ca47e2f><p class="label" data-v-6ca47e2f>Appearance</p><div class="appearance-action" data-v-6ca47e2f><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-6ca47e2f data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-2840085c data-v-3597ebf2><span class="container" data-v-3597ebf2><span class="top" data-v-3597ebf2></span><span class="middle" data-v-3597ebf2></span><span class="bottom" data-v-3597ebf2></span></span></button></div></div></div></div><div class="divider" data-v-2840085c><div class="divider-line" data-v-2840085c></div></div></div><!----></header><div class="VPLocalNav empty fixed" data-v-cb931ff4 data-v-c17e40bf><div class="container" data-v-c17e40bf><!----><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-c17e40bf data-v-88669269><button data-v-88669269>Return to top</button><!----></div></div></div><!----><div class="VPContent" id="VPContent" data-v-cb931ff4 data-v-6a83e20a><div class="VPDoc has-aside" data-v-6a83e20a data-v-81f89caf><!--[--><!--]--><div class="container" data-v-81f89caf><div class="aside" data-v-81f89caf><div class="aside-curtain" data-v-81f89caf></div><div class="aside-container" data-v-81f89caf><div class="aside-content" data-v-81f89caf><div class="VPDocAside" data-v-81f89caf data-v-2f246d4c><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-2f246d4c data-v-b2d618e4><div class="content" data-v-b2d618e4><div class="outline-marker" data-v-b2d618e4></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-b2d618e4>On this page</div><ul class="VPDocOutlineItem root" data-v-b2d618e4 data-v-35c93968><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-2f246d4c></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-81f89caf><div class="content-container" data-v-81f89caf><!-Line truncated
<script>window.__VP_HASH_MAP__=JSON.parse("{\"architecture_agent-system.md\":\"Coj6mPZw\",\"architecture_configuration.md\":\"BsVGi7ja\",\"architecture_dependencies-and-contracts.md\":\"ByRODJZC\",\"architecture_generated-documentation.md\":\"qELen1k6\",\"architecture_identity.md\":\"CB0DkYo9\",\"architecture_index.md\":\"DJpk2YHf\",\"architecture_messaging-and-work-intake.md\":\"Q7MxXQDB\",\"architecture_migration-decisions.md\":\"oN2eGfag\",\"architecture_organisation.md\":\"mAPb3vCC\",\"architecture_package-review.md\":\"7BZCENBd\",\"architecture_plugins-and-extensions.md\":\"DmzsC2M0\",\"architecture_policy.md\":\"4L33IZiY\",\"architecture_safe-change-and-recovery.md\":\"CdYeF0XF\",\"archive_archie-core-architecture.md\":\"Bqg5-owD\",\"archive_archie-core-skills-prd-v2.md\":\"D3RVdXag\",\"archive_archie-core-skills-prd.md\":\"D1oUBHEN\",\"archive_decisions.md\":\"DkenJ6mD\",\"archive_design.md\":\"BwF1bH5l\",\"archive_prds_multi-agent-collaboration.md\":\"zqWXF3O0\",\"archive_prds_typescript-plugin-engine.md\":\"DBR1GKuy\",\"archive_prds_yaegi-plugin-system.md\":\"V36uzfZI\",\"index.md\":\"BdS51Ijr\",\"prds_01-project-management.md\":\"DEpuIAgg\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Archie\",\"description\":\"Documentation for the Archie personal agent platform.\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/favicon.svg\",\"nav\":[{\"text\":\"Architecture\",\"link\":\"/architecture/\"}],\"sidebar\":{\"/architecture/\":[{\"text\":\"Architecture\",\"items\":[{\"text\":\"Overview\",\"link\":\"/architecture/\"},{\"text\":\"Repository Organisation\",\"link\":\"/architecture/organisation\"},{\"text\":\"Dependencies and Contracts\",\"link\":\"/architecture/dependencies-and-contracts\"},{\"text\":\"Agent System\",\"link\":\"/architecture/agent-system\"},{\"text\":\"Configuration\",\"link\":\"/architecture/configuration\"},{\"text\":\"Identity\",\"link\":\"/architecture/identity\"},{\"text\":\"Messaging and Work Intake\",\"link\":\"/architecture/messaging-and-work-intake\"},{\"text\":\"Plugins and Extensions\",\"link\":\"/architecture/plugins-and-extensions\"},{\"text\":\"Policy System\",\"link\":\"/architecture/policy\"},{\"text\":\"Safe Change and Recovery\",\"link\":\"/architecture/safe-change-and-recovery\"},{\"text\":\"Generated Documentation\",\"link\":\"/architecture/generated-documentation\"},{\"text\":\"Domain and Feature Review Procedure\",\"link\":\"/architecture/package-review\"},{\"text\":\"Migration Decisions\",\"link\":\"/architecture/migration-decisions\"}]}]},\"search\":{\"provider\":\"local\"},\"footer\":{\"message\":\"Built with VitePress.\",\"copyright\":\"Archie\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
</body>
</html>
@@ -1,127 +0,0 @@
<!DOCTYPE html>
<html lang="en-US" dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>archie-core v2 Architecture -- Design Document | Archie</title>
<meta name="description" content="Documentation for the Archie personal agent platform.">
<meta name="generator" content="VitePress v1.6.4">
<link rel="preload stylesheet" href="/assets/style.C4BXn3EN.css" as="style">
<link rel="preload stylesheet" href="/vp-icons.css" as="style">
<script type="module" src="/assets/app.HIbJYLU1.js"></script>
<link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="modulepreload" href="/assets/chunks/theme.B97NJxv0.js">
<link rel="modulepreload" href="/assets/chunks/framework.BWuWLRhz.js">
<link rel="modulepreload" href="/assets/archive_archie-core-architecture.md.Bqg5-owD.lean.js">
<link rel="icon" href="/favicon.svg">
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
</head>
<body>
<div id="app"><div class="Layout" data-v-cb931ff4><!--[--><!--]--><!--[--><span tabindex="-1" data-v-8ae66126></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-8ae66126>Skip to content</a><!--]--><!----><header class="VPNav" data-v-cb931ff4 data-v-a1925027><div class="VPNavBar" data-v-a1925027 data-v-2840085c><div class="wrapper" data-v-2840085c><div class="container" data-v-2840085c><div class="title" data-v-2840085c><div class="VPNavBarTitle" data-v-2840085c data-v-e7a29354><a class="title" href="/" data-v-e7a29354><!--[--><!--]--><!--[--><img class="VPImage logo" src="/favicon.svg" alt data-v-eec9b196><!--]--><span data-v-e7a29354>Archie</span><!--[--><!--]--></a></div></div><div class="content" data-v-2840085c><div class="content-body" data-v-2840085c><!--[--><!--]--><div class="VPNavBarSearch search" data-v-2840085c><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-2840085c data-v-ded89948><span id="main-nav-aria-label" class="visually-hidden" data-v-ded89948> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/architecture/" tabindex="0" data-v-ded89948 data-v-0a9a3d21><!--[--><span data-v-0a9a3d21>Architecture</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-2840085c data-v-4b074154><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-4b074154 data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-2840085c data-v-6ca47e2f data-v-b980f1c3><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-b980f1c3><span class="vpi-more-horizontal icon" data-v-b980f1c3></span></button><div class="menu" data-v-b980f1c3><div class="VPMenu" data-v-b980f1c3 data-v-a1767133><!----><!--[--><!--[--><!----><div class="group" data-v-6ca47e2f><div class="item appearance" data-v-6ca47e2f><p class="label" data-v-6ca47e2f>Appearance</p><div class="appearance-action" data-v-6ca47e2f><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-6ca47e2f data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-2840085c data-v-3597ebf2><span class="container" data-v-3597ebf2><span class="top" data-v-3597ebf2></span><span class="middle" data-v-3597ebf2></span><span class="bottom" data-v-3597ebf2></span></span></button></div></div></div></div><div class="divider" data-v-2840085c><div class="divider-line" data-v-2840085c></div></div></div><!----></header><div class="VPLocalNav empty fixed" data-v-cb931ff4 data-v-c17e40bf><div class="container" data-v-c17e40bf><!----><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-c17e40bf data-v-88669269><button data-v-88669269>Return to top</button><!----></div></div></div><!----><div class="VPContent" id="VPContent" data-v-cb931ff4 data-v-6a83e20a><div class="VPDoc has-aside" data-v-6a83e20a data-v-81f89caf><!--[--><!--]--><div class="container" data-v-81f89caf><div class="aside" data-v-81f89caf><div class="aside-curtain" data-v-81f89caf></div><div class="aside-container" data-v-81f89caf><div class="aside-content" data-v-81f89caf><div class="VPDocAside" data-v-81f89caf data-v-2f246d4c><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-2f246d4c data-v-b2d618e4><div class="content" data-v-b2d618e4><div class="outline-marker" data-v-b2d618e4></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-b2d618e4>On this page</div><ul class="VPDocOutlineItem root" data-v-b2d618e4 data-v-35c93968><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-2f246d4c></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-81f89caf><div class="content-container" data-v-81f89caf><!-Line truncated
<span class="line"><span>archie.task.feature -- Feasibility workflow tasks</span></span>
<span class="line"><span>archie.task.default -- Implement workflow tasks</span></span>
<span class="line"><span>archie.task.bootstrap -- Bootstrap diagnostic tasks</span></span></code></pre></div><p>Daemon publishes to the appropriate subject based on label routing. Agents subscribe to subjects they&#39;re configured to handle.</p><h3 id="agent-communication-per-task" tabindex="-1">Agent communication (per-task) <a class="header-anchor" href="#agent-communication-per-task" aria-label="Permalink to &quot;Agent communication (per-task)&quot;">​</a></h3><div class="language-events vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">events</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>archie.agent.&lt;task_id&gt;.response -- Agent output: summaries, PR bodies, results. Daemon reviews before human delivery.</span></span>
<span class="line"><span>archie.agent.&lt;task_id&gt;.system -- Internal comms: log dumps, data requests, health, PII warnings. Never forwarded unprompted.</span></span>
<span class="line"><span>archie.agent.&lt;task_id&gt;.request -- Optional: agent requests additional data from the daemon.</span></span></code></pre></div><p>The daemon gatekeeps the response channel -- no agent output reaches a human without daemon review.</p><h3 id="jetstream-durability" tabindex="-1">JetStream durability <a class="header-anchor" href="#jetstream-durability" aria-label="Permalink to &quot;JetStream durability&quot;">​</a></h3><p>Tasks are published with JetStream persistence. On agent container failure, NATS redelivers. The daemon doesn&#39;t need retry logic -- NATS handles it.</p><hr><h2 id="_3-persistent-volume" tabindex="-1">3. Persistent volume <a class="header-anchor" href="#_3-persistent-volume" aria-label="Permalink to &quot;3. Persistent volume&quot;">​</a></h2><blockquote><p><strong>Status: partially implemented.</strong> <code>task.json</code>, <code>/data/worktree</code>, optional per-repo <code>/data/repo</code> 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. <code>session.jsonl</code>, <code>memory.jsonl</code>, and staged plugin volumes remain unimplemented.</p></blockquote><h3 id="data-layout" tabindex="-1">/data/ layout <a class="header-anchor" href="#data-layout" aria-label="Permalink to &quot;/data/ layout&quot;">​</a></h3><div class="language-tree vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">tree</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>/data/</span></span>
<span class="line"><span>|---- task.json # Full task payload (owner, repo, issue, title, body, labels, workflow)</span></span>
<span class="line"><span>|---- session.jsonl # Agent session transcript (appended per stage)</span></span>
<span class="line"><span>|---- memory.jsonl # Optional: cross-session memory (persisted per project)</span></span>
<span class="line"><span>|---- plugins/ # Bundled plugins from the skill (daemon-staged, overrides worktree)</span></span>
<span class="line"><span>|---- worktree/ # Read-only mount of the cloned repo (managed by daemon)</span></span></code></pre></div><h3 id="task-json" tabindex="-1">task.json <a class="header-anchor" href="#task-json" aria-label="Permalink to &quot;task.json&quot;">​</a></h3><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;id&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">42</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;owner&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;sam&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;repo&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;example-service&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;issue_number&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">170</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;title&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Add /copy command for messages and session transcripts&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;body&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;labels&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;enhancement&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;archie&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;workflow&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;implement&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;branch&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;archie/issue-170&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;plan&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;config&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;base_branch&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;main&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;gate&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;gofumpt&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;-w&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;go&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;vet&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;./...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;go&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;test&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;-race&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;./...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ],</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;protect&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;_templ.go&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;ecosystem&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;go&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;test_glob&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;*_test.go&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;nats&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;url&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;nats://archie-core:4222&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;response_subject&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;archie.agent.42.response&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;system_subject&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;archie.agent.42.system&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;request_subject&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;archie.agent.42.request&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>The daemon writes <code>task.json</code> to the volume before the container starts. The agent reads it on boot.</p><h3 id="volume-lifecycle" tabindex="-1">Volume lifecycle <a class="header-anchor" href="#volume-lifecycle" aria-label="Permalink to &quot;Volume lifecycle&quot;">​</a></h3><ul><li>Created on task start (persistent per-repo if configured)</li><li>Kept until terminal outcome (<code>pr_open</code>, <code>merged</code>, <code>rejected</code>, <code>closed_wont_do</code>) OR TTL expiry</li><li>Parked tasks keep their volume for inspection and requeue reuse</li><li>Cleanup is a daemon responsibility</li></ul><hr><h2 id="_4-container-management" tabindex="-1">4. Container management <a class="header-anchor" href="#_4-container-management" aria-label="Permalink to &quot;4. Container management&quot;">​</a></h2><blockquote><p><strong>Status: implemented with a flatter schema than the sketch below.</strong> <code>[containers]</code> configures the image, concurrency, uptime, pull policy, and persistent-storage TTL. <code>Repo.PersistentStorage</code> opts a repository into the per-repo Docker volume and Git object cache. The backend abstraction exists in <code>internal/storage</code>; additional storage types and structured per-backend configuration remain future work.</p></blockquote><h3 id="daemon-config" tabindex="-1">Daemon config <a class="header-anchor" href="#daemon-config" aria-label="Permalink to &quot;Daemon config&quot;">​</a></h3><div class="language-toml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">toml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Container lifecycle</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">containers</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">max_concurrency = </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">4</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # max simultaneous agent containers</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">max_uptime = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;30m&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # grace period after task completion before kill</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">volume_ttl = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;72h&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # max volume age before cleanup (overrides terminal wait)</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Image strategy</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">containers</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">image</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">registry = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;ghcr.io/sam/archie-agent:latest&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # primary: pull from registry</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">registry_pull = </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # allow pulls</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">dockerfile = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;./Dockerfile.agent&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # fallback: build locally</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">dockerfile_build = </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # allow builds</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Persistent storage</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">containers</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">persistent_storage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">type = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;docker&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # docker (volume), bind, s3, sftp, nfs</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">path = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;archie-data&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # volume name or mount path</span></span></code></pre></div><h3 id="per-repo-persistent-storage-override" tabindex="-1">Per-repo persistent storage override <a class="header-anchor" href="#per-repo-persistent-storage-override" aria-label="Permalink to &quot;Per-repo persistent storage override&quot;">​</a></h3><div class="language-toml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">toml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[[</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">repos</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">owner = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;sam&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">name = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;example-service&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">persistent_storage = { type = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;bind&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, path = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;./archie-core-data/projects/example-service&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span></code></pre></div><p>When configured, each task for this repo mounts the same bind path. Memory persists across sessions. The agent writes to <code>MEMORY.md</code> in this directory.</p><h3 id="agent-image" tabindex="-1">Agent image <a class="header-anchor" href="#agent-image" aria-label="Permalink to &quot;Agent image&quot;">​</a></h3><p>A fat Docker image containing:</p><ul><li>archie-agent binary</li><li>NATS client library</li><li>LLM provider SDKs (ai-sdk runtime)</li><li>Base tools: git, gh, go, golangci-lint, gofumpt, node, python, ruff, pytest, etc.</li><li>esbuild (for TypeScript plugin transpilation)</li><li>Yaegi interpreter (bundled in the binary)</li></ul><p>Pre-built and published to a registry. The daemon pulls on startup. Users can provide their own image via config.</p><hr><h2 id="_5-extensibility-layers" tabindex="-1">5. Extensibility layers <a class="header-anchor" href="#_5-extensibility-layers" aria-label="Permalink to &quot;5. Extensibility layers&quot;">​</a></h2><blockquote><p><strong>Reconciliation note.</strong> 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 <em>does</em> exist -- and is implemented, tested, and already in production -- is described in the sibling PRD <code>docs/prds/yaegi-plugin-system.md</code>, whose three phases (custom gate functions, custom workflow stages, skill scripts) are marked &quot;implemented&quot; and match disk state exactly as of commit <code>d45f21d</code>. That implementation is narrower and shaped differently than what follows:</p><ul><li>It has <strong>no skill-bundling concept</strong> -- <code>.archie/gate.go</code> and <code>.archie/stages/*.go</code> are repo-level, not shipped inside a skill&#39;s <code>plugins/</code> directory; skill scripts (<code>.archie/skills/&lt;skill&gt;/scripts/*.go</code>) are the closest analog but none of the five current skills ship a <code>scripts/</code> directory yet.</li><li>It has <strong>no daemon-side core plugin registry</strong> -- no <code>Plugin</code> interface, no <code>Register(daemon *Daemon)</code>, no <code>~/.config/archie/plugins/</code> loader. Yaegi today only interprets small, narrowly-scoped <code>.go</code> files (gates, stages, scripts) in-process inside <code>archied</code>, using generated symbol tables (<code>internal/gate/gateextract</code>, <code>internal/workflow/wfextract</code>) rather than a general extension-registration interface.</li><li>Custom stages are <strong>auto-discovered and run in filename order</strong>, not routed by name from <code>config.toml</code> -- the workflow engine has no data-driven stage graph today, so the <code>[[workflows.stages]]</code> config sketch below does not correspond to real config.</li></ul><p>Before implementation begins, decide: does Layer 1/Layer 2 as described below <em>replace</em> the existing three Yaegi surfaces, or does it <em>extend</em> them (e.g., teach the existing loaders to also read from a skill&#39;s <code>plugins/</code> directory, and add a genuinely new daemon-side <code>Plugin</code> 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.</p></blockquote><h3 id="layer-1-skills-archie-wf" tabindex="-1">Layer 1: Skills (<code>archie-wf-*</code>) <a class="header-anchor" href="#layer-1-skills-archie-wf" aria-label="Permalink to &quot;Layer 1: Skills (`archie-wf-*`)&quot;">​</a></h3><blockquote><p><strong>Status: cosmetic only.</strong> Five <code>SKILL.md</code> files exist today (<code>ecosystem-node</code>, <code>ecosystem-python</code>, <code>go-quality-gate</code>, <code>security-audit</code>, <code>tdd-bugfix</code>) at <code>.archie/skills/&lt;name&gt;/SKILL.md</code> -- a single flat repo-relative location, no worktree-vs-user-level split, no <code>archie-wf-*</code> naming. Each has a <code>metadata.archie</code> block with only <code>tools</code> and <code>engine</code> keys (no <code>plugins</code>, no <code>budget_usd</code>). <strong>No Go code parses SKILL.md frontmatter, discovers skills, or does progressive disclosure</strong> -- grepping for a skill loader, catalog, or frontmatter parser across the repo returns nothing. The workflow <code>Mission</code> strings that drive agent behavior today are hand-written Go string literals in <code>internal/workflow/{impleLine truncated
<span class="line"><span>.agents/skills/archie-wf-implement/SKILL.md</span></span>
<span class="line"><span>.agents/skills/archie-wf-feasibility/SKILL.md</span></span>
<span class="line"><span>~/.archie/skills/archie-wf-default/SKILL.md (user-level -- fallback)</span></span></code></pre></div><p>The agent discovers skills at workflow start. The skill matching the task&#39;s workflow type is loaded first. If absent, falls back to <code>archie-wf-default</code>. If that&#39;s absent too, the agent works from AGENTS.md conventions and best practices.</p><h4 id="extended-agentskills-io-format" tabindex="-1">Extended agentskills.io format <a class="header-anchor" href="#extended-agentskills-io-format" aria-label="Permalink to &quot;Extended agentskills.io format&quot;">​</a></h4><p>Skills follow the standard spec (<code>name</code>, <code>description</code>, <code>version</code>, <code>SKILL.md</code> body) with archie-specific metadata:</p><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">---</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">archie-wf-tdd</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> Test-driven bugfix workflow for archie-core. Reproduce the bug with failing tests, prove the repro, fix the code</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> without touching tests.</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">version</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1.0.0</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">metadata</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> archie</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> plugins</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># bundled Yaegi plugins shipped with this skill</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">plugins/custom-gate.go</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # repo-specific gate logic</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">plugins/gosec-check.go</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # security scanner integration</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> tools</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">golangci-lint</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">gofumpt</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">task</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> engine</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">any</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> budget_usd</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">2.00</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">---</span></span></code></pre></div><h4 id="progressive-disclosure" tabindex="-1">Progressive disclosure <a class="header-anchor" href="#progressive-disclosure" aria-label="Permalink to &quot;Progressive disclosure&quot;">​</a></h4><p>Per the agentskills.io spec:</p><ol><li><strong>Catalog</strong> (~100 tokens): <code>name</code> + <code>description</code> loaded at workflow start</li><li><strong>Instructions</strong> (&lt;5000 tokens): Full <code>SKILL.md</code> body when the skill is activated</li><li><strong>Resources</strong> (as needed): References, scripts, and bundled plugins loaded on demand</li></ol><h4 id="bundled-plugins" tabindex="-1">Bundled plugins <a class="header-anchor" href="#bundled-plugins" aria-label="Permalink to &quot;Bundled plugins&quot;">​</a></h4><p>A skill&#39;s <code>plugins/</code> directory contains Yaegi <code>.go</code> files. These are loaded by the agent at workflow start alongside the skill instructions. The daemon copies them to <code>/data/plugins/</code> before the container starts.</p><p>If <code>/data/plugins/</code> already has a plugin with the same name (from persistent project storage), the volume version wins. Conflicts are logged by the daemon.</p><h3 id="layer-2-core-plugins" tabindex="-1">Layer 2: Core plugins <a class="header-anchor" href="#layer-2-core-plugins" aria-label="Permalink to &quot;Layer 2: Core plugins&quot;">​</a></h3><blockquote><p><strong>Status: aspirational, zero code.</strong> No <code>Plugin</code> interface, no plugin registry, no <code>~/.config/archie/plugins/</code> loader exists anywhere in the repo (confirmed by grep for <code>Plugin</code>, plugin registry, and <code>Register(daemon</code> -- zero matches). Yaegi is a real dependency (<code>traefik/yaegi v0.16.1</code>) and is genuinely wired up, but only for the three narrow surfaces in sec.5&#39;s reconciliation note above, all interpreted in-process inside <code>archied</code> -- not for extending the daemon with new forge/ticketing/storage/secrets/notify implementations as described below.</p></blockquote><p>Core plugins live at <code>~/.config/archie/plugins/</code> and extend the daemon itself:</p><div class="language-tree vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">tree</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>~/.config/archie/plugins/</span></span>
<span class="line"><span>|---- forge-gitea.go # Gitea forge implementation</span></span>
<span class="line"><span>|---- forge-gitlab.go # GitLab forge implementation</span></span>
<span class="line"><span>|---- ticketing-jira.go # Jira ticketing integration</span></span>
<span class="line"><span>|---- ticketing-linear.go # Linear ticketing integration</span></span>
<span class="line"><span>|---- storage-s3.go # S3 persistent storage backend</span></span>
<span class="line"><span>|---- vault-secrets.go # HashiCorp Vault integration</span></span>
<span class="line"><span>|---- notify-servicenow.go # ServiceNow integration</span></span></code></pre></div><h4 id="loading" tabindex="-1">Loading <a class="header-anchor" href="#loading" aria-label="Permalink to &quot;Loading&quot;">​</a></h4><p>Loaded by the daemon at startup via Yaegi. Each plugin registers itself with the daemon&#39;s extension registry:</p><div class="language-go vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">go</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Plugin interface (Go, interpreted via Yaegi)</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">type</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Plugin</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> interface</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Version</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Register</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">daemon</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> *</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Daemon</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">error</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>The daemon discovers <code>.go</code> files, evaluates them, extracts the plugin symbol, and calls <code>Register()</code>. Failed plugins are logged and skipped -- the daemon starts with remaining plugins.</p><h4 id="what-core-plugins-can-do" tabindex="-1">What core plugins can do <a class="header-anchor" href="#what-core-plugins-can-do" aria-label="Permalink to &quot;What core plugins can do&quot;">​</a></h4><ul><li><strong>Forges</strong> -- implement the <code>forge.Forge</code> interface. Register themselves as available forge types.</li><li><strong>Ticketing</strong> -- implement a ticketing interface. Poll external systems, format issues into the standard <code>forge.Issue</code> struct.</li><li><strong>Storage backends</strong> -- implement a storage interface. Provide volume population and cleanup.</li><li><strong>Secrets</strong> -- implement a vault interface. Inject credentials into <code>/data/secrets/</code> before agent start.</li><li><strong>Notifications</strong> -- implement a notify interface. Deliver PRDs, status updates beyond the built-in webhook.</li></ul><hr><h2 id="_6-task-lifecycle-v2" tabindex="-1">6. Task lifecycle (v2) <a class="header-anchor" href="#_6-task-lifecycle-v2" aria-label="Permalink to &quot;6. Task lifecycle (v2)&quot;">​</a></h2><blockquote><p><strong>Status: implemented.</strong> NATS JetStream is now the task distribution path (<code>internal/nats/client.go</code>, <code>internal/daemon/daemon.go:drainNATS()</code>). Docker containers spawn per task (<code>internal/container/pool.go</code>). The flow below matches the running code post-e4d11b1.</p></blockquote><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>Discover -&gt; Publish to JetStream -&gt; Agent consumes -&gt; running(workflow:stage)</span></span>
<span class="line"><span> v</span></span>
<span class="line"><span> pr_open -&gt; merged | rejected</span></span>
<span class="line"><span> v</span></span>
<span class="line"><span> waiting_human -&gt; (approved) -&gt; requeue</span></span>
<span class="line"><span> v</span></span>
<span class="line"><span> parked</span></span></code></pre></div><h3 id="detailed-flow" tabindex="-1">Detailed flow <a class="header-anchor" href="#detailed-flow" aria-label="Permalink to &quot;Detailed flow&quot;">​</a></h3><ol><li><strong>Discover</strong> -- daemon polls forges for labelled/assigned issues</li><li><strong>Publish</strong> -- daemon publishes task to <code>archie.task.&lt;workflow_type&gt;</code> JetStream subject</li><li><strong>Spawn</strong> -- daemon creates task volume, writes <code>task.json</code>, stages bundled plugins</li><li><strong>Start container</strong> -- <code>docker run</code> with volume mounts, network (NATS), resource limits</li><li><strong>Agent boots</strong> -- reads <code>task.json</code> from <code>/data/</code>, connects to NATS, discovers skills, loads bundled plugins</li><li><strong>Run workflow</strong> -- agent executes routed workflow stages. Reports progress to system channel. Result to response channel.</li><li><strong>Daemon reviews</strong> -- reads agent response. Forwards to human channels (issue comment, label update, PR). System messages stay internal.</li><li><strong>Grace period</strong> -- agent stays alive for <code>max_uptime</code>. Handles follow-ups (gate re-runs, human replies forwarded by daemon).</li><li><strong>Kill</strong> -- daemon kills container. Volume cleaned up on terminal outcome or TTL expiry.</li></ol><hr><h2 id="_7-agent-daemon-human-flow" tabindex="-1">7. Agent -&gt; daemon -&gt; human flow <a class="header-anchor" href="#_7-agent-daemon-human-flow" aria-label="Permalink to &quot;7. Agent -&gt; daemon -&gt; human flow&quot;">​</a></h2><div class="language-flow vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">flow</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>,---------, response ,---------, reviewed ,----------,</span></span>
<span class="line"><span>| Agent |------------ -&gt; | Daemon |------------ -&gt; | Human |</span></span>
<span class="line"><span>| | system | | queried | channels |</span></span>
<span class="line"><span>| |------------ -&gt; | |&lt;-------------| |</span></span>
<span class="line"><span>|------------ |------------ |-------------</span></span>
<span class="line"><span> |</span></span>
<span class="line"><span> |---- Issue comments (parked, PR, waiting)</span></span>
<span class="line"><span> |---- Label updates (archie:queued -&gt; archie:working -&gt; archie:pr)</span></span>
<span class="line"><span> |---- Notify webhook (feasibility PRD delivered)</span></span>
<span class="line"><span> |---- SSE dashboard (real-time observability)</span></span></code></pre></div><p>The agent writes whatever it wants to <code>response</code>. The daemon reviews it. No agent output reaches a human unprompted. The <code>system</code> channel is purely internal -- the daemon reads it for observability and debugging, never forwards it.</p><hr><h2 id="_8-implementation-phases" tabindex="-1">8. Implementation phases <a class="header-anchor" href="#_8-implementation-phases" aria-label="Permalink to &quot;8. Implementation phases&quot;">​</a></h2><blockquote><p>Updated 2026-07-24 against actual repo state (see sec.0). Items marked <strong>done</strong> 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.</p></blockquote><h3 id="phase-1-binary-split-nats" tabindex="-1">Phase 1: Binary split + NATS <a class="header-anchor" href="#phase-1-binary-split-nats" aria-label="Permalink to &quot;Phase 1: Binary split + NATS&quot;">​</a></h3><ul><li><s>Split <code>archied</code> into daemon binary</s> -- <strong>done</strong>, <code>cmd/archied</code> exists</li><li><s>Create <code>archie-agent</code> binary</s> -- <strong>done, but partial</strong>: <code>cmd/archie-agent</code> exists and executes one workflow <em>stage</em> per invocation over a versioned stdin/stdout JSON protocol (<code>internal/agentexec</code>, protocol v1). Still needed: promote it from a single-stage subprocess worker to the PRD&#39;s per-task process, and move workflow routing/sequencing (<code>workflow.Route</code>/<code>workflow.Run</code>) out of <code>archied</code> and into it.</li><li><s>Add NATS to both (JetStream for task queue, request-reply for comms)</s> -- <strong>done</strong>. <code>[nats]</code> is optional, supports anonymous local mode and token authentication via <code>token_env</code>, and leaves <code>internal/events.Bus</code> as the local observability fan-out.</li><li><s>Daemon publishes, agent consumes, results return via NATS</s> -- <strong>done</strong>. Task discovery uses JetStream work-queue subjects; autonomous stages use JetStream requests plus core NATS reply inboxes.</li><li>Current single-process mode preserved for development (<code>--local</code> flag) -- effectively already true: <code>inprocess</code><code>[agent] mode</code> is the <em>default</em>, not an opt-in fallback, so this constraint is satisfied but should be revisited once subprocess/container modes are the default.</li></ul><h3 id="phase-2-docker-sandbox" tabindex="-1">Phase 2: Docker sandbox <a class="header-anchor" href="#phase-2-docker-sandbox" aria-label="Permalink to &quot;Phase 2: Docker sandbox&quot;">​</a></h3><ul><li>Docker agent image (fat, with tools) -- not started</li><li>Daemon container lifecycle: spawn, volume create, env inject, kill -- not started</li><li><s>Persistent volumes with TTL</s> -- <strong>done</strong>: configured repos receive a persistent Docker volume plus a per-repo Git object cache; both are automatically reaped using <code>containers.volume_ttl</code>.</li><li><s><code>max_concurrency</code> enforcement</s> -- <strong>done</strong>: SQLite and NATS drains dispatch different repositories concurrently up to <code>[containers].max_concurrency</code>; same-repo tasks remain serialized by default.</li><li>Grace period <code>max_uptime</code> -- not started</li><li><strong>Groundwork already in place:</strong> <code>agentexec.Runner</code> (<code>InProcessRunner</code>/<code>SubprocessRunner</code>) is an interface designed, per its own doc comments, to be swapped for a container-backed runner without touching workflow orchestration -- implement <code>ContainerRunner</code> against this interface rather than redesigning the execution boundary.</li></ul><h3 id="phase-3-skills-bundled-plugins" tabindex="-1">Phase 3: Skills + bundled plugins <a class="header-anchor" href="#phase-3-skills-bundled-plugins" aria-label="Permalink to &quot;Phase 3: Skills + bundled plugins&quot;">​</a></h3><ul><li>agentskills.io spec implementation (progressive disclosure) -- not started; current SKILL.md files are unparsed documentation (see sec.5)</li><li><code>archie-wf-*</code> skill discovery from worktree and user paths -- not started; current skills live at a single flat <code>.archie/skills/</code> path with different naming</li><li>Bundled plugin loading via Yaegi from skill&#39;s <code>plugins/</code> directory -- not started, but <strong>has a working substrate to extend</strong>: <code>internal/gate/gateeval</code>, <code>internal/workflow/wfeval</code>, and <code>internal/skillscript</code> already interpret <code>.go</code> files via Yaegi with generated symbol tables and panic recovery (see <code>docs/prds/yaegi-plugin-system.md</code>, Phases 1--3, done). This phase should teach thLine truncated
<script>window.__VP_HASH_MAP__=JSON.parse("{\"architecture_agent-system.md\":\"Coj6mPZw\",\"architecture_configuration.md\":\"BsVGi7ja\",\"architecture_dependencies-and-contracts.md\":\"ByRODJZC\",\"architecture_generated-documentation.md\":\"qELen1k6\",\"architecture_identity.md\":\"CB0DkYo9\",\"architecture_index.md\":\"DJpk2YHf\",\"architecture_messaging-and-work-intake.md\":\"Q7MxXQDB\",\"architecture_migration-decisions.md\":\"oN2eGfag\",\"architecture_organisation.md\":\"mAPb3vCC\",\"architecture_package-review.md\":\"7BZCENBd\",\"architecture_plugins-and-extensions.md\":\"DmzsC2M0\",\"architecture_policy.md\":\"4L33IZiY\",\"architecture_safe-change-and-recovery.md\":\"CdYeF0XF\",\"archive_archie-core-architecture.md\":\"Bqg5-owD\",\"archive_archie-core-skills-prd-v2.md\":\"D3RVdXag\",\"archive_archie-core-skills-prd.md\":\"D1oUBHEN\",\"archive_decisions.md\":\"DkenJ6mD\",\"archive_design.md\":\"BwF1bH5l\",\"archive_prds_multi-agent-collaboration.md\":\"zqWXF3O0\",\"archive_prds_typescript-plugin-engine.md\":\"DBR1GKuy\",\"archive_prds_yaegi-plugin-system.md\":\"V36uzfZI\",\"index.md\":\"BdS51Ijr\",\"prds_01-project-management.md\":\"DEpuIAgg\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Archie\",\"description\":\"Documentation for the Archie personal agent platform.\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/favicon.svg\",\"nav\":[{\"text\":\"Architecture\",\"link\":\"/architecture/\"}],\"sidebar\":{\"/architecture/\":[{\"text\":\"Architecture\",\"items\":[{\"text\":\"Overview\",\"link\":\"/architecture/\"},{\"text\":\"Repository Organisation\",\"link\":\"/architecture/organisation\"},{\"text\":\"Dependencies and Contracts\",\"link\":\"/architecture/dependencies-and-contracts\"},{\"text\":\"Agent System\",\"link\":\"/architecture/agent-system\"},{\"text\":\"Configuration\",\"link\":\"/architecture/configuration\"},{\"text\":\"Identity\",\"link\":\"/architecture/identity\"},{\"text\":\"Messaging and Work Intake\",\"link\":\"/architecture/messaging-and-work-intake\"},{\"text\":\"Plugins and Extensions\",\"link\":\"/architecture/plugins-and-extensions\"},{\"text\":\"Policy System\",\"link\":\"/architecture/policy\"},{\"text\":\"Safe Change and Recovery\",\"link\":\"/architecture/safe-change-and-recovery\"},{\"text\":\"Generated Documentation\",\"link\":\"/architecture/generated-documentation\"},{\"text\":\"Domain and Feature Review Procedure\",\"link\":\"/architecture/package-review\"},{\"text\":\"Migration Decisions\",\"link\":\"/architecture/migration-decisions\"}]}]},\"search\":{\"provider\":\"local\"},\"footer\":{\"message\":\"Built with VitePress.\",\"copyright\":\"Archie\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
</body>
</html>
@@ -1,183 +0,0 @@
<!DOCTYPE html>
<html lang="en-US" dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>archie-core Skills System -- PRD | Archie</title>
<meta name="description" content="Documentation for the Archie personal agent platform.">
<meta name="generator" content="VitePress v1.6.4">
<link rel="preload stylesheet" href="/assets/style.C4BXn3EN.css" as="style">
<link rel="preload stylesheet" href="/vp-icons.css" as="style">
<script type="module" src="/assets/app.HIbJYLU1.js"></script>
<link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="modulepreload" href="/assets/chunks/theme.B97NJxv0.js">
<link rel="modulepreload" href="/assets/chunks/framework.BWuWLRhz.js">
<link rel="modulepreload" href="/assets/archive_archie-core-skills-prd-v2.md.D3RVdXag.lean.js">
<link rel="icon" href="/favicon.svg">
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
</head>
<body>
<div id="app"><div class="Layout" data-v-cb931ff4><!--[--><!--]--><!--[--><span tabindex="-1" data-v-8ae66126></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-8ae66126>Skip to content</a><!--]--><!----><header class="VPNav" data-v-cb931ff4 data-v-a1925027><div class="VPNavBar" data-v-a1925027 data-v-2840085c><div class="wrapper" data-v-2840085c><div class="container" data-v-2840085c><div class="title" data-v-2840085c><div class="VPNavBarTitle" data-v-2840085c data-v-e7a29354><a class="title" href="/" data-v-e7a29354><!--[--><!--]--><!--[--><img class="VPImage logo" src="/favicon.svg" alt data-v-eec9b196><!--]--><span data-v-e7a29354>Archie</span><!--[--><!--]--></a></div></div><div class="content" data-v-2840085c><div class="content-body" data-v-2840085c><!--[--><!--]--><div class="VPNavBarSearch search" data-v-2840085c><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-2840085c data-v-ded89948><span id="main-nav-aria-label" class="visually-hidden" data-v-ded89948> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/architecture/" tabindex="0" data-v-ded89948 data-v-0a9a3d21><!--[--><span data-v-0a9a3d21>Architecture</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-2840085c data-v-4b074154><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-4b074154 data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-2840085c data-v-6ca47e2f data-v-b980f1c3><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-b980f1c3><span class="vpi-more-horizontal icon" data-v-b980f1c3></span></button><div class="menu" data-v-b980f1c3><div class="VPMenu" data-v-b980f1c3 data-v-a1767133><!----><!--[--><!--[--><!----><div class="group" data-v-6ca47e2f><div class="item appearance" data-v-6ca47e2f><p class="label" data-v-6ca47e2f>Appearance</p><div class="appearance-action" data-v-6ca47e2f><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-6ca47e2f data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-2840085c data-v-3597ebf2><span class="container" data-v-3597ebf2><span class="top" data-v-3597ebf2></span><span class="middle" data-v-3597ebf2></span><span class="bottom" data-v-3597ebf2></span></span></button></div></div></div></div><div class="divider" data-v-2840085c><div class="divider-line" data-v-2840085c></div></div></div><!----></header><div class="VPLocalNav empty fixed" data-v-cb931ff4 data-v-c17e40bf><div class="container" data-v-c17e40bf><!----><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-c17e40bf data-v-88669269><button data-v-88669269>Return to top</button><!----></div></div></div><!----><div class="VPContent" id="VPContent" data-v-cb931ff4 data-v-6a83e20a><div class="VPDoc has-aside" data-v-6a83e20a data-v-81f89caf><!--[--><!--]--><div class="container" data-v-81f89caf><div class="aside" data-v-81f89caf><div class="aside-curtain" data-v-81f89caf></div><div class="aside-container" data-v-81f89caf><div class="aside-content" data-v-81f89caf><div class="VPDocAside" data-v-81f89caf data-v-2f246d4c><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-2f246d4c data-v-b2d618e4><div class="content" data-v-b2d618e4><div class="outline-marker" data-v-b2d618e4></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-b2d618e4>On this page</div><ul class="VPDocOutlineItem root" data-v-b2d618e4 data-v-35c93968><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-2f246d4c></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-81f89caf><div class="content-container" data-v-81f89caf><!-Line truncated
<span class="line"><span>archie.yaml (repo root)</span></span>
<span class="line"><span>.archie/archie.yaml (subdirectory, one level deep)</span></span></code></pre></div><h3 id="_1-2-schema" tabindex="-1">1.2 Schema <a class="header-anchor" href="#_1-2-schema" aria-label="Permalink to &quot;1.2 Schema&quot;">​</a></h3><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># archie.yaml</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">version</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;1&quot;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Project identity</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">project</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">my-go-service</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> language</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> repo</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">github.com/sam/my-go-service</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># How archie-core connects to this project</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">connection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> interfaces</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">github</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # respond to assigned issues</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">linear</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # respond to labelled tickets</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">webhook</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # respond to HTTP POSTs</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> github</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> repo</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">sam/my-go-service</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> issue_labels</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> ready</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;archie:ready&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # issues with this label get claimed</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> claimed</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;archie:claimed&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # archie sets this when working</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> done</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;archie:done&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # archie sets this after PR</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> pr</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> base</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">main</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> draft</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Skills -- playbooks archie-core loads to know how to work</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">skills</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> paths</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.archie/skills/</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # project-local skills</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">~/.archie/skills/</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # per-user skills</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> remotes</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">github.com/sam/archie-skills@v1</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # shared skill library</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Sandbox -- what&#39;s available in the container</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">sandbox</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> image</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">ghcr.io/sam/archie-sandbox:latest</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> tools</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">golangci-lint</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">gofumpt</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">task</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">gh</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">docker</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> env</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> GOFLAGS</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;-mod=readonly&quot;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Gates -- archie-core must pass these before committing</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">gates</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go test -race -count=1 ./...</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> timeout</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">300</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> lint</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">golangci-lint run ./...</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> timeout</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">120</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> format</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">gofumpt -w . &amp;&amp; git diff --exit-code</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> deadcode</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">task deadcode</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> optional</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Quality pipeline -- which gates run when</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">quality</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> pre_commit</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">lint</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">format</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> pre_push</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">deadcode</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Commit conventions</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">commit</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> format</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">conventional</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> signoff</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Branch conventions</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">branch</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> format</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;{type}/cat-{number}-{kebab-description}&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> types</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> feat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Feature work&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> fix</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Bug fixes&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Test additions&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> chore</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Maintenance&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> refactor</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Code restructuring&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> docs</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Documentation&quot;</span></span></code></pre></div><hr><h2 id="_2-skills-playbooks" tabindex="-1">2. Skills (playbooks) <a class="header-anchor" href="#_2-skills-playbooks" aria-label="Permalink to &quot;2. Skills (playbooks)&quot;">​</a></h2><p>Skills are Markdown documents that tell archie-core <strong>how</strong> to perform specific tasks. They follow the <a href="https://agentskills.io/specification" target="_blank" rel="noreferrer">agentskills.io</a> format, making them portable across compatible LLM coding agents.</p><h3 id="_2-1-format" tabindex="-1">2.1 Format <a class="header-anchor" href="#_2-1-format" aria-label="Permalink to &quot;2.1 Format&quot;">​</a></h3><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>go-testing/</span></span>
<span class="line"><span>├── SKILL.md # Required: frontmatter + instructions</span></span>
<span class="line"><span>├── references/ # Optional: supplementary docs</span></span>
<span class="line"><span>│ └── coverage.md</span></span>
<span class="line"><span>├── scripts/ # Optional: executable helpers</span></span>
<span class="line"><span>│ └── bench.sh</span></span>
<span class="line"><span>└── assets/ # Optional: templates</span></span>
<span class="line"><span> └── test.vscode.code-snippets</span></span></code></pre></div><h3 id="_2-2-skill-md" tabindex="-1">2.2 SKILL.md <a class="header-anchor" href="#_2-2-skill-md" aria-label="Permalink to &quot;2.2 SKILL.md&quot;">​</a></h3><div class="language-markdown vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">markdown</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">---</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go-quality-gate</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> Run the full Go quality pipeline:</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> gofumpt, go fix, golangci-lint, go test -race, and task deadcode.</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> Use before any commit in a Go project.</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">version</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1.0.0</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">metadata</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> archie</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Which gates this skill covers</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> gates</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">lint</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">format</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">deadcode</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Required sandbox tools</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> tools</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">golangci-lint</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">gofumpt</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">task</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Preferred engine (if multiple available)</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> engine</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">any</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Max spend for this skill</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> budget_usd</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">2.00</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">---</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;"># Go Quality Gate</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">## When to use</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">Before committing any Go change. After implementing a feature or fix.</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">## Procedure</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">Run in this exact order. If any step fails, fix the issue before continuing.</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">1.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> `gofumpt -w .`</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">2.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> `go fix ./...`</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">3.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> `golangci-lint run ./...`</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">4.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> `go test -race -count=1 ./...`</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">5.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> `task deadcode`</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">## Verification</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">All five steps must exit 0. If </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">`task deadcode`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> fails on unrelated packages,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">scope it to only changed packages: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">`golangci-lint run --tests=false --enable-only=unused,staticcheck ./changed/pkg/...`</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">## Common failures</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> `golangci-lint`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: unused function -- remove it or add </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">`//nolint:unused`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> comment</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> `go test -race`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: data race -- protect with mutex or channel</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> `task deadcode`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: pre-existing dead code in unrelated package -- scope to changed packages</span></span></code></pre></div><h3 id="_2-3-skill-metadata-arcie-specific" tabindex="-1">2.3 Skill metadata (arcie-specific) <a class="header-anchor" href="#_2-3-skill-metadata-arcie-specific" aria-label="Permalink to &quot;2.3 Skill metadata (arcie-specific)&quot;">​</a></h3><p>Skills carry archie-specific metadata under <code>metadata.archie</code>:</p><table tabindex="0"><thead><tr><th>Field</th><th>Purpose</th></tr></thead><tbody><tr><td><code>gates</code></td><td>Which gates from <code>archie.yaml</code> this skill covers</td></tr><tr><td><code>tools</code></td><td>Sandbox tools this skill needs</td></tr><tr><td><code>engine</code></td><td>Preferred execution engine</td></tr><tr><td><code>model</code></td><td>Preferred model for this skill</td></tr><tr><td><code>budget_usd</code></td><td>Max spend ceiling</td></tr><tr><td><code>timeout</code></td><td>Max seconds</td></tr><tr><td><code>worktree</code></td><td>Whether to create isolated worktree</td></tr></tbody></table><h3 id="_2-4-progressive-disclosure" tabindex="-1">2.4 Progressive disclosure <a class="header-anchor" href="#_2-4-progressive-disclosure" aria-label="Permalink to &quot;2.4 Progressive disclosure&quot;">​</a></h3><p>Following the skills.sh model to keep context lean:</p><ol><li><strong>Advertise</strong> (~100 tokens per skill): <code>name</code> + <code>description</code> loaded at startup</li><li><strong>Activate</strong> (&lt;5000 tokens): Full SKILL.md body loaded when skill is relevant</li><li><strong>Resources</strong> (as needed): References, scripts, assets loaded on demand</li></ol><hr><h2 id="_3-how-archie-core-processes-an-issue" tabindex="-1">3. How archie-core processes an issue <a class="header-anchor" href="#_3-how-archie-core-processes-an-issue" aria-label="Permalink to &quot;3. How archie-core processes an issue&quot;">​</a></h2><p>This is the core loop. When an issue lands with the configured label:</p><h3 id="_3-1-analyse" tabindex="-1">3.1 Analyse <a class="header-anchor" href="#_3-1-analyse" aria-label="Permalink to &quot;3.1 Analyse&quot;">​</a></h3><ol><li>Read issue title, body, labels, comments</li><li>Load relevant skills from the project&#39;s <code>archie.yaml</code></li><li>Determine scope: which packages, files, and gates are in play</li><li>Determine branch type (<code>feat/</code>, <code>fix/</code>, <code>test/</code>, etc.) from issue labels or conventional commit prefix</li></ol><h3 id="_3-2-claim" tabindex="-1">3.2 Claim <a class="header-anchor" href="#_3-2-claim" aria-label="Permalink to &quot;3.2 Claim&quot;">​</a></h3><ol><li>Set issue label to <code>archie:claimed</code></li><li>Comment: &quot;Archie claimed this. Branch: <code>&lt;branch&gt;</code>&quot;</li><li>Create isolated worktree from <code>main</code></li></ol><h3 id="_3-3-implement" tabindex="-1">3.3 Implement <a class="header-anchor" href="#_3-3-implement" aria-label="Permalink to &quot;3.3 Implement&quot;">​</a></h3><ol><li>Load full skill bodies for each relevant skill</li><li>Read project source and tests in the affected area</li><li>Implement changes, writing tests first where applicable</li><li>Run targeted tests iteratively</li></ol><h3 id="_3-4-gate" tabindex="-1">3.4 Gate <a class="header-anchor" href="#_3-4-gate" aria-label="Permalink to &quot;3.4 Gate&quot;">​</a></h3><ol><li>Run all gates from the quality pipeline in order</li><li>Fix any failures, re-running from the failing gate</li><li>Audit diff for secrets, unrelated changes, attribution</li></ol><h3 id="_3-5-deliver" tabindex="-1">3.5 Deliver <a class="header-anchor" href="#_3-5-deliver" aria-label="Permalink to &quot;3.5 Deliver&quot;">​</a></h3><ol><li>Commit with conventional format: <code>feat(scope): description</code></li><li>Push branch</li><li>Open PR to <code>main</code> with: <ul><li>Summary of changes</li><li>Acceptance criteria addressed</li><li>Gate results</li><li>Link back to source issue/Linear ticket</li></ul></li><li>Set issue label to <code>archie:done</code></li><li>Comment with PR URL</li></ol><h3 id="_3-6-on-failure" tabindex="-1">3.6 On failure <a class="header-anchor" href="#_3-6-on-failure" aria-label="Permalink to &quot;3.6 On failure&quot;">​</a></h3><p>If any gate fails irrecoverably:</p><ol><li>Leave issue as <code>archie:claimed</code></li><li>Comment with exact blocker, failed command, and worktree path</li><li>Preserve worktree for inspection</li><li>Do not open a broken PR</li></ol><hr><h2 id="_4-engine-abstraction" tabindex="-1">4. Engine abstraction <a class="header-anchor" href="#_4-engine-abstraction" aria-label="Permalink to &quot;4. Engine abstraction&quot;">​</a></h2><p>arcie-core can delegate implementation to difLine truncated
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">claude</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Claude Code CLI -- full agent loop</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">sonnet</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> budget_usd</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">5.00</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">codex</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # OpenAI Codex CLI</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">gpt-5.1-codex-max</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">raw</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Direct LLM -- no agent loop, single prompt</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">gpt-4o-mini</span></span></code></pre></div><p>Each engine provides the same interface:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>Engine:</span></span>
<span class="line"><span> - Run(prompt, tools, budget, timeout) -&gt; Result</span></span>
<span class="line"><span> - Skills() -&gt; []SkillName</span></span>
<span class="line"><span> - Capabilities() -&gt; {streaming, reasoning, vision, agentic}</span></span></code></pre></div><p>For skills that need a specific engine, the skill metadata overrides:</p><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">metadata</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> archie</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> engine</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">claude</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # this skill only works with Claude</span></span></code></pre></div><hr><h2 id="_5-skills-in-practice" tabindex="-1">5. Skills in practice <a class="header-anchor" href="#_5-skills-in-practice" aria-label="Permalink to &quot;5. Skills in practice&quot;">​</a></h2><h3 id="_5-1-shared-skill-library" tabindex="-1">5.1 Shared skill library <a class="header-anchor" href="#_5-1-shared-skill-library" aria-label="Permalink to &quot;5.1 Shared skill library&quot;">​</a></h3><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># archie.yaml</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">skills</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> remotes</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">github.com/sam/archie-skills@v1</span></span></code></pre></div><p>Skills from the shared library are available alongside project-local skills. The agent loads them on demand when an issue references relevant concepts.</p><h3 id="_5-3-skill-that-wraps-an-external-tool" tabindex="-1">5.3 Skill that wraps an external tool <a class="header-anchor" href="#_5-3-skill-that-wraps-an-external-tool" aria-label="Permalink to &quot;5.3 Skill that wraps an external tool&quot;">​</a></h3><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">---</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">trivy-scan</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> Scan container images and filesystems for vulnerabilities using Trivy.</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> Use when asked about security scanning, CVEs, or container hardening.</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">metadata</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> archie</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> tools</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">docker</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">trivy</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> engine</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">any</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">---</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">## Procedure</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">1. `trivy image --severity HIGH,CRITICAL &lt;image&gt;`</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">2. If findings exist, report each CVE with package, version, and fixed version</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">3. If no findings, report clean</span></span></code></pre></div><hr><h2 id="_6-comparison-archie-core-vs-existing-systems" tabindex="-1">6. Comparison: archie-core vs existing systems <a class="header-anchor" href="#_6-comparison-archie-core-vs-existing-systems" aria-label="Permalink to &quot;6. Comparison: archie-core vs existing systems&quot;">​</a></h2><table tabindex="0"><thead><tr><th></th><th>archie-core</th><th>Claude Code</th><th>Codex CLI</th><th>GitHub Actions</th><th>Hermes Agent</th></tr></thead><tbody><tr><td><strong>How it receives work</strong></td><td>GitHub issue assignment, Linear label, webhook</td><td>Chat, slash commands</td><td>Chat, slash commands</td><td>YAML triggers (push, PR, schedule)</td><td>Chat, cron, webhooks</td></tr><tr><td><strong>What it does</strong></td><td>Analyse → implement → gate → PR</td><td>Analyse → implement → gate → PR</td><td>Analyse → implement → gate → PR</td><td>Run arbitrary shell commands</td><td>Analyse → implement → gate → PR</td></tr><tr><td><strong>Skills</strong></td><td>SKILL.md (agentskills.io)</td><td>SKILL.md (native)</td><td>SKILL.md (agentskills.io)</td><td>Composite actions</td><td>SKILL.md (native)</td></tr><tr><td><strong>Gates</strong></td><td>Named checkpoints in archie.yaml</td><td>Ad-hoc (CLAUDE.md + lint)</td><td>Ad-hoc</td><td>Steps in jobs</td><td>Skills with gates</td></tr><tr><td><strong>Engine pluggable</strong></td><td>Yes</td><td>No (fixed to Claude)</td><td>No (fixed to Codex)</td><td>No (fixed to GitHub)</td><td>Yes (provider config)</td></tr><tr><td><strong>Worktree isolation</strong></td><td>Yes</td><td>Yes (<code>--worktree</code>)</td><td>No</td><td>No (ephemeral runner)</td><td>No</td></tr><tr><td><strong>Blueprint/cron</strong></td><td>Export to Hermes</td><td>No</td><td>No</td><td>Schedule trigger</td><td>Native</td></tr><tr><td><strong>Where it runs</strong></td><td>Docker sandbox</td><td>Host</td><td>Host or sandbox</td><td>GitHub runner</td><td>Host, Docker, Modal, SSH</td></tr></tbody></table><hr><h2 id="_7-implementation-phases" tabindex="-1">7. Implementation phases <a class="header-anchor" href="#_7-implementation-phases" aria-label="Permalink to &quot;7. Implementation phases&quot;">​</a></h2><h3 id="phase-1-workflow-file-and-gates-current-mvp" tabindex="-1">Phase 1: Workflow file and gates (current MVP) <a class="header-anchor" href="#phase-1-workflow-file-and-gates-current-mvp" aria-label="Permalink to &quot;Phase 1: Workflow file and gates (current MVP)&quot;">​</a></h3><ul><li><code>archie.yaml</code> parser</li><li>Gate runner executing shell commands and checking exit codes</li><li>Skill discovery from project and user paths</li><li>GitHub interface: claim issues, create worktrees, open PRs</li></ul><h3 id="phase-2-skills" tabindex="-1">Phase 2: Skills <a class="header-anchor" href="#phase-2-skills" aria-label="Permalink to &quot;Phase 2: Skills&quot;">​</a></h3><ul><li>SKILL.md progressive disclosure (advertise → activate → resources)</li><li>archie-specific metadata parsing</li><li>Skill chaining: skills that depend on other skills</li><li><code>archie skills list/install</code> CLI</li></ul><h3 id="phase-3-engine-abstraction" tabindex="-1">Phase 3: Engine abstraction <a class="header-anchor" href="#phase-3-engine-abstraction" aria-label="Permalink to &quot;Phase 3: Engine abstraction&quot;">​</a></h3><ul><li>Engine interface definition</li><li>Claude Code adapter</li><li>Raw LLM adapter</li><li>Engine fallback chain</li><li>Per-skill engine preferences</li></ul><h3 id="phase-4-advanced-features" tabindex="-1">Phase 4: Advanced features <a class="header-anchor" href="#phase-4-advanced-features" aria-label="Permalink to &quot;Phase 4: Advanced features&quot;">​</a></h3><ul><li>Gate overrides per skill</li><li>Skill templates for project scaffolding (<code>archie init --skill go-service</code>)</li><li>Remote skill libraries (git repos as skill sources)</li><li>Blueprint export to Hermes cron</li></ul><h3 id="phase-5-additional-interfaces" tabindex="-1">Phase 5: Additional interfaces <a class="header-anchor" href="#phase-5-additional-interfaces" aria-label="Permalink to &quot;Phase 5: Additional interfaces&quot;">​</a></h3><ul><li>Linear webhook integration</li><li>Generic webhook interface for arbitrary sources</li><li>CLI command interface (<code>archie run &lt;command&gt;</code>)</li></ul><hr><h2 id="_8-open-questions" tabindex="-1">8. Open questions <a class="header-anchor" href="#_8-open-questions" aria-label="Permalink to &quot;8. Open questions&quot;">​</a></h2><ol><li><strong>Claim protocol:</strong> Single-claim (arcie takes one issue at a time) or queue-based (claims N issues, works through them sequentially)?</li><li><strong>Concurrent worktrees:</strong> Allow multiple archie-core instances working on different issues simultaneously?</li><li><strong>PR merging:</strong> ShoulLine truncated
<script>window.__VP_HASH_MAP__=JSON.parse("{\"architecture_agent-system.md\":\"Coj6mPZw\",\"architecture_configuration.md\":\"BsVGi7ja\",\"architecture_dependencies-and-contracts.md\":\"ByRODJZC\",\"architecture_generated-documentation.md\":\"qELen1k6\",\"architecture_identity.md\":\"CB0DkYo9\",\"architecture_index.md\":\"DJpk2YHf\",\"architecture_messaging-and-work-intake.md\":\"Q7MxXQDB\",\"architecture_migration-decisions.md\":\"oN2eGfag\",\"architecture_organisation.md\":\"mAPb3vCC\",\"architecture_package-review.md\":\"7BZCENBd\",\"architecture_plugins-and-extensions.md\":\"DmzsC2M0\",\"architecture_policy.md\":\"4L33IZiY\",\"architecture_safe-change-and-recovery.md\":\"CdYeF0XF\",\"archive_archie-core-architecture.md\":\"Bqg5-owD\",\"archive_archie-core-skills-prd-v2.md\":\"D3RVdXag\",\"archive_archie-core-skills-prd.md\":\"D1oUBHEN\",\"archive_decisions.md\":\"DkenJ6mD\",\"archive_design.md\":\"BwF1bH5l\",\"archive_prds_multi-agent-collaboration.md\":\"zqWXF3O0\",\"archive_prds_typescript-plugin-engine.md\":\"DBR1GKuy\",\"archive_prds_yaegi-plugin-system.md\":\"V36uzfZI\",\"index.md\":\"BdS51Ijr\",\"prds_01-project-management.md\":\"DEpuIAgg\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Archie\",\"description\":\"Documentation for the Archie personal agent platform.\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/favicon.svg\",\"nav\":[{\"text\":\"Architecture\",\"link\":\"/architecture/\"}],\"sidebar\":{\"/architecture/\":[{\"text\":\"Architecture\",\"items\":[{\"text\":\"Overview\",\"link\":\"/architecture/\"},{\"text\":\"Repository Organisation\",\"link\":\"/architecture/organisation\"},{\"text\":\"Dependencies and Contracts\",\"link\":\"/architecture/dependencies-and-contracts\"},{\"text\":\"Agent System\",\"link\":\"/architecture/agent-system\"},{\"text\":\"Configuration\",\"link\":\"/architecture/configuration\"},{\"text\":\"Identity\",\"link\":\"/architecture/identity\"},{\"text\":\"Messaging and Work Intake\",\"link\":\"/architecture/messaging-and-work-intake\"},{\"text\":\"Plugins and Extensions\",\"link\":\"/architecture/plugins-and-extensions\"},{\"text\":\"Policy System\",\"link\":\"/architecture/policy\"},{\"text\":\"Safe Change and Recovery\",\"link\":\"/architecture/safe-change-and-recovery\"},{\"text\":\"Generated Documentation\",\"link\":\"/architecture/generated-documentation\"},{\"text\":\"Domain and Feature Review Procedure\",\"link\":\"/architecture/package-review\"},{\"text\":\"Migration Decisions\",\"link\":\"/architecture/migration-decisions\"}]}]},\"search\":{\"provider\":\"local\"},\"footer\":{\"message\":\"Built with VitePress.\",\"copyright\":\"Archie\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
</body>
</html>
-198
View File
@@ -1,198 +0,0 @@
<!DOCTYPE html>
<html lang="en-US" dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>archie-core Workflows &amp; Skills -- Product Requirements Document | Archie</title>
<meta name="description" content="Documentation for the Archie personal agent platform.">
<meta name="generator" content="VitePress v1.6.4">
<link rel="preload stylesheet" href="/assets/style.C4BXn3EN.css" as="style">
<link rel="preload stylesheet" href="/vp-icons.css" as="style">
<script type="module" src="/assets/app.HIbJYLU1.js"></script>
<link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="modulepreload" href="/assets/chunks/theme.B97NJxv0.js">
<link rel="modulepreload" href="/assets/chunks/framework.BWuWLRhz.js">
<link rel="modulepreload" href="/assets/archive_archie-core-skills-prd.md.D1oUBHEN.lean.js">
<link rel="icon" href="/favicon.svg">
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
</head>
<body>
<div id="app"><div class="Layout" data-v-cb931ff4><!--[--><!--]--><!--[--><span tabindex="-1" data-v-8ae66126></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-8ae66126>Skip to content</a><!--]--><!----><header class="VPNav" data-v-cb931ff4 data-v-a1925027><div class="VPNavBar" data-v-a1925027 data-v-2840085c><div class="wrapper" data-v-2840085c><div class="container" data-v-2840085c><div class="title" data-v-2840085c><div class="VPNavBarTitle" data-v-2840085c data-v-e7a29354><a class="title" href="/" data-v-e7a29354><!--[--><!--]--><!--[--><img class="VPImage logo" src="/favicon.svg" alt data-v-eec9b196><!--]--><span data-v-e7a29354>Archie</span><!--[--><!--]--></a></div></div><div class="content" data-v-2840085c><div class="content-body" data-v-2840085c><!--[--><!--]--><div class="VPNavBarSearch search" data-v-2840085c><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-2840085c data-v-ded89948><span id="main-nav-aria-label" class="visually-hidden" data-v-ded89948> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/architecture/" tabindex="0" data-v-ded89948 data-v-0a9a3d21><!--[--><span data-v-0a9a3d21>Architecture</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-2840085c data-v-4b074154><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-4b074154 data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-2840085c data-v-6ca47e2f data-v-b980f1c3><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-b980f1c3><span class="vpi-more-horizontal icon" data-v-b980f1c3></span></button><div class="menu" data-v-b980f1c3><div class="VPMenu" data-v-b980f1c3 data-v-a1767133><!----><!--[--><!--[--><!----><div class="group" data-v-6ca47e2f><div class="item appearance" data-v-6ca47e2f><p class="label" data-v-6ca47e2f>Appearance</p><div class="appearance-action" data-v-6ca47e2f><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-6ca47e2f data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-2840085c data-v-3597ebf2><span class="container" data-v-3597ebf2><span class="top" data-v-3597ebf2></span><span class="middle" data-v-3597ebf2></span><span class="bottom" data-v-3597ebf2></span></span></button></div></div></div></div><div class="divider" data-v-2840085c><div class="divider-line" data-v-2840085c></div></div></div><!----></header><div class="VPLocalNav empty fixed" data-v-cb931ff4 data-v-c17e40bf><div class="container" data-v-c17e40bf><!----><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-c17e40bf data-v-88669269><button data-v-88669269>Return to top</button><!----></div></div></div><!----><div class="VPContent" id="VPContent" data-v-cb931ff4 data-v-6a83e20a><div class="VPDoc has-aside" data-v-6a83e20a data-v-81f89caf><!--[--><!--]--><div class="container" data-v-81f89caf><div class="aside" data-v-81f89caf><div class="aside-curtain" data-v-81f89caf></div><div class="aside-container" data-v-81f89caf><div class="aside-content" data-v-81f89caf><div class="VPDocAside" data-v-81f89caf data-v-2f246d4c><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-2f246d4c data-v-b2d618e4><div class="content" data-v-b2d618e4><div class="outline-marker" data-v-b2d618e4></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-b2d618e4>On this page</div><ul class="VPDocOutlineItem root" data-v-b2d618e4 data-v-35c93968><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-2f246d4c></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-81f89caf><div class="content-container" data-v-81f89caf><!-Line truncated
<span class="line"><span>archie.yaml (repo root)</span></span>
<span class="line"><span>.archie/archie.yaml (subdirectory, one level deep)</span></span></code></pre></div><p>If no file is found, archie-core uses built-in defaults (read, write, bash).</p><h3 id="_1-2-schema" tabindex="-1">1.2 Schema <a class="header-anchor" href="#_1-2-schema" aria-label="Permalink to &quot;1.2 Schema&quot;">​</a></h3><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># archie.yaml -- complete schema</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">version</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;1&quot;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Project identity</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">project</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">my-go-service</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> language</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Available skills (directories or individual files)</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">skills</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> paths</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.archie/skills/</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # project-local skills</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">~/.archie/skills/</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # per-user skills</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">github.com/org/shared-skills@v1</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # remote skill repo</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> skills</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go-testing</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # named skill from any path</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">security-audit</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Execution engines in preference order</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">engines</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">claude</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Claude Code CLI</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">sonnet</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">codex</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # OpenAI Codex</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pi</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Pi agent harness</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">raw</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Direct LLM without agent wrapper</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Sandbox definition (what the Docker container provides)</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">sandbox</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> image</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">ghcr.io/samcharles93/archie-sandbox:latest</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> tools</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">golangci-lint</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">gofumpt</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">task</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">gh</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">docker</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> mounts</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/var/run/docker.sock</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> target</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/var/run/docker.sock</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> env</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> GOFLAGS</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;-mod=readonly&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> CGO_ENABLED</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;0&quot;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Gates -- ordered checkpoints that must pass</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">gates</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go test -race -count=1 ./...</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> timeout</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">300</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;All tests must pass&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> lint</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">golangci-lint run ./...</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> timeout</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">120</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Zero lint issues&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> format</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">gofumpt -w . &amp;&amp; git diff --exit-code</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;No formatting drift&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> vet</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go vet ./...</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;No vet warnings&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> deadcode</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">task deadcode</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> optional</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # non-blocking gate</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Dead code check (advisory)&quot;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Quality pipeline -- ordered sequence of gate groups</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">quality</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> pre_commit</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">test</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">lint</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">format</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">vet</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> pre_push</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">deadcode</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Commit conventions</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">commit</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> format</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">conventional</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # conventional commits</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> signoff</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> template</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;feat({scope}): {description}&quot;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># PR conventions</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">pr</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> template</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.github/PULL_REQUEST_TEMPLATE.md</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> checks</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">test</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">lint</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Project-specific commands (what `archie run &lt;name&gt;` executes)</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">commands</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> build</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go build -o bin/app ./cmd/server</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Build the binary&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> serve</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go run ./cmd/server</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Start dev server&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go test ./...</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Run all tests&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> lint</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">golangci-lint run ./...</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Run linter&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> all</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">gofumpt -w .</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go fix ./...</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">golangci-lint run ./...</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go test -race ./...</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">task deadcode</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Full quality pipeline&quot;</span></span></code></pre></div><h3 id="_1-3-design-decisions-with-rationale" tabindex="-1">1.3 Design decisions (with rationale) <a class="header-anchor" href="#_1-3-design-decisions-with-rationale" aria-label="Permalink to &quot;1.3 Design decisions (with rationale)&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Decision</th><th>Rationale</th></tr></thead><tbody><tr><td>YAML over TOML/JSON</td><td>Already dominant in CI (GitHub Actions, GitLab CI, Taskfile). Human-readable with comments.</td></tr><tr><td>Single file over multi-file</td><td>Task discovery (like <code>Taskfile.yml</code>), devcontainer conventions. Avoids directory sprawl.</td></tr><tr><td>Gates as named checkpoints</td><td>GitHub Actions job model. Gates can be composed into quality pipelines, selected individually, or skipped with <code>--skip</code>.</td></tr><tr><td>Engines as ordered preference list</td><td>Supports deterministic fallback between available engines. Each engine declares its own tool surface.</td></tr><tr><td>Skills as paths + references</td><td>Matches devcontainer features (paths resolve to directories) and skills.sh (namespaced references).</td></tr><tr><td>Commands section for direct invocation</td><td>Arnie can <code>archie run test</code> without an agent turn. Thin wrapper over the sandbox.</td></tr><tr><td>Quality pipeline groups gates</td><td>Pre-commit vs pre-push vs pre-merge distinction. Some gates are required, some advisory.</td></tr></tbody></table><hr><h2 id="_2-skills" tabindex="-1">2. Skills <a class="header-anchor" href="#_2-skills" aria-label="Permalink to &quot;2. Skills&quot;">​</a></h2><h3 id="_2-1-format" tabindex="-1">2.1 Format <a class="header-anchor" href="#_2-1-format" aria-label="Permalink to &quot;2.1 Format&quot;">​</a></h3><p>Skills follow the <a href="https://agentskills.io/specification" target="_blank" rel="noreferrer">agentskills.io</a> specification:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>skill-name/</span></span>
<span class="line"><span>├── SKILL.md # Required: YAML frontmatter + Markdown instructions</span></span>
<span class="line"><span>├── scripts/ # Optional: executable helpers</span></span>
<span class="line"><span>├── references/ # Optional: longer docs, checklists</span></span>
<span class="line"><span>└── assets/ # Optional: templates, configs</span></span></code></pre></div><p><strong>SKILL.md frontmatter:</strong></p><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">---</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go-testing</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> Run Go tests with race detection, coverage, and benchmark analysis.</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> Use when asked to test Go code, run the test suite, or check coverage.</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">version</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1.0.0</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">metadata</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> archie</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> gates</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># gates this skill requires</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> tools</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">golangci-lint</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># sandbox tools it needs</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> engine</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">any</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # engine preference</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">compatibility</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">Requires Go 1.22+</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">---</span></span></code></pre></div><h3 id="_2-2-progressive-disclosure" tabindex="-1">2.2 Progressive disclosure <a class="header-anchor" href="#_2-2-progressive-disclosure" aria-label="Permalink to &quot;2.2 Progressive disclosure&quot;">​</a></h3><p>Following the skills.sh and Claude Code patterns:</p><ol><li><strong>Advertise</strong> (~100 tokens): <code>name</code> + <code>description</code> loaded at session start</li><li><strong>Load</strong> (&lt;5000 tokens recommended): Full SKILL.md body when skill activates</li><li><strong>Resources</strong> (as needed): Scripts, references, assets loaded on demand</li></ol><h3 id="_2-3-archie-specific-metadata" tabindex="-1">2.3 archie-specific metadata <a class="header-anchor" href="#_2-3-archie-specific-metadata" aria-label="Permalink to &quot;2.3 archie-specific metadata&quot;">​</a></h3><p>Skills can carry archie-specific frontmatter under <code>metadata.archie</code>:</p><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">metadata</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> archie</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> gates</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">lint</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># must-pass gates before skill runs</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> tools</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">docker</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># sandbox tools required</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> engine</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">any</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # preferred engine</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">gpt-4o</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # preferred model</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> budget_usd</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">2.00</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # max spend ceiling</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> timeout</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">600</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # max seconds</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> worktree</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # create isolated worktree</span></span></code></pre></div><h3 id="_2-4-skill-sources-inspired-by-devcontainer-features-dagger-modules" tabindex="-1">2.4 Skill sources (inspired by devcontainer features + Dagger modules) <a class="header-anchor" href="#_2-4-skill-sources-inspired-by-devcontainer-features-dagger-modules" aria-label="Permalink to &quot;2.4 Skill sources (inspired by devcontainer features + Dagger modules)&quot;">​</a></h3><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>skills:</span></span>
<span class="line"><span> paths:</span></span>
<span class="line"><span> - .archie/skills/ # project-local (committed)</span></span>
<span class="line"><span> - ~/.archie/skills/ # per-user (personal)</span></span>
<span class="line"><span> skills:</span></span>
<span class="line"><span> - go-testing # by name from any path</span></span>
<span class="line"><span> remotes:</span></span>
<span class="line"><span> - github.com/samcharles93/archie-skills@v1 # tagged git repo</span></span>
<span class="line"><span> - https://agentskills.io/registry # community registry</span></span></code></pre></div><hr><h2 id="_3-execution-engine-model" tabindex="-1">3. Execution Engine Model <a class="header-anchor" href="#_3-execution-engine-model" aria-label="Permalink to &quot;3. Execution Engine Model&quot;">​</a></h2><h3 id="_3-1-engine-abstraction" tabindex="-1">3.1 Engine abstraction <a class="header-anchor" href="#_3-1-engine-abstraction" aria-label="Permalink to &quot;3.1 Engine abstraction&quot;">​</a></h3><p>Each engine provides the same interface. The workflow file declares preference order; archie-core resolves the first available engine at runtime.</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>Engine interface:</span></span>
<span class="line"><span> - Run(prompt, tools[], budget, timeout) -&gt; Result</span></span>
<span class="line"><span> - Tools() -&gt; []ToolSchema</span></span>
<span class="line"><span> - Capabilities() -&gt; {streaming, reasoning, vision, agentic}</span></span></code></pre></div><h3 id="_3-2-supported-engines" tabindex="-1">3.2 Supported engines <a class="header-anchor" href="#_3-2-supported-engines" aria-label="Permalink to &quot;3.2 Supported engines&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Engine</th><th>Type</th><th>What it provides</th></tr></thead><tbody><tr><td><code>claude</code></td><td>Claude Code CLI</td><td>Full agent loop, tool use, worktrees, subagents</td></tr><tr><td><code>codex</code></td><td>OpenAI Codex CLI</td><td>Agentic coding with sandbox</td></tr><tr><td><code>pi</code></td><td>Pi agent harness</td><td>Minimalist coding agent, stdio protocol</td></tr><tr><td><code>raw</code></td><td>Direct LLM call</td><td>Single-turn prompt, no agent loop. For simple scripts.</td></tr></tbody></table><h3 id="_3-3-engine-selection-logic" tabindex="-1">3.3 Engine selection logic <a class="header-anchor" href="#_3-3-engine-selection-logic" aria-label="Permalink to &quot;3.3 Engine selection logic&quot;">​</a></h3><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">engines</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">claude</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">sonnet</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> budget_usd</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">5.00</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">raw</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">gpt-4o-mini</span></span></code></pre></div><p>arcie-core tries engines in order and selects the first available, authenticated engine. Each engine declares its budget ceiling.</p><hr><h2 id="_4-additional-features" tabindex="-1">4. Additional Features <a class="header-anchor" href="#_4-additional-features" aria-label="Permalink to &quot;4. Additional Features&quot;">​</a></h2><h3 id="_4-1-worktree-isolation-worktree-true" tabindex="-1">4.1 Worktree isolation (<code>worktree: true</code>) <a class="header-anchor" href="#_4-1-worktree-isolation-worktree-true" aria-label="Permalink to &quot;4.1 Worktree isolation (`worktree: true`)&quot;">​</a></h3><p>Inspired by Claude Code&#39;s <code>--worktree</code> flag. When a skill or command sets <code>worktree: true</code>, archie-core:</p><ol><li>Creates an isolated git worktree at <code>.archie/worktrees/&lt;skill-name&gt;-&lt;timestamp&gt;/</code></li><li>Runs all gates and implementation in that worktree</li><li>Cleans up on success, preserves on failure for inspection</li></ol><p>This prevents concurrent agent sessions from conflicting and enables parallel agent execution.</p><h3 id="_4-2-skill-chaining-and-composition" tabindex="-1">4.2 Skill chaining and composition <a class="header-anchor" href="#_4-2-skill-chaining-and-composition" aria-label="Permalink to &quot;4.2 Skill chaining and composition&quot;">​</a></h3><p>Skills can declare dependencies, forming a DAG:</p><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">---</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">full-ci</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">Complete CI pipeline including security audit</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">metadata</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> archie</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> requires</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go-testing</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">security-audit</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run_sequential</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">---</span></span></code></pre></div><p>arcie-core resolves the dependency graph and runs skills in order (parallel where possible, respecting <code>run_sequential</code>). This is conceptually similar to GitHub Actions <code>needs</code> and Taskfile <code>deps</code>.</p><h3 id="_4-3-gate-overrides-per-skill" tabindex="-1">4.3 Gate overrides per skill <a class="header-anchor" href="#_4-3-gate-overrides-per-skill" aria-label="Permalink to &quot;4.3 Gate overrides per skill&quot;">​</a></h3><p>A skill can override project-level gates:</p><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">metadata</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> archie</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> gates</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go test -short ./...</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # override: faster test for this skill</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> lint</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">skip</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # skip lint for this skill</span></span></code></pre></div><p>Three override modes: <code>override</code> (replace command), <code>skip</code> (omit gate), <code>add</code> (add new gate requirement).</p><h3 id="_4-4-skill-templates-scaffolding" tabindex="-1">4.4 Skill templates (scaffolding) <a class="header-anchor" href="#_4-4-skill-templates-scaffolding" aria-label="Permalink to &quot;4.4 Skill templates (scaffolding)&quot;">​</a></h3><p>Skills can carry an <code>assets/</code> directory with templates. When archie-core initializes a new project, it can apply skill templates:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>skill-name/</span></span>
<span class="line"><span>├── SKILL.md</span></span>
<span class="line"><span>└── assets/</span></span>
<span class="line"><span> ├── .archie.yaml.tmpl # Template workflow file</span></span>
<span class="line"><span> ├── Taskfile.yml.tmpl # Template task runner</span></span>
<span class="line"><span> └── .golangci.yml.tmpl # Template linter config</span></span></code></pre></div><p><code>archie init --skill go-service</code> scaffolds a new project with the go-service skill&#39;s templates applied.</p><h3 id="_4-5-blueprint-export-hermes-cron-integration" tabindex="-1">4.5 Blueprint export (Hermes cron integration) <a class="header-anchor" href="#_4-5-blueprint-export-hermes-cron-integration" aria-label="Permalink to &quot;4.5 Blueprint export (Hermes cron integration)&quot;">​</a></h3><p>Following the Hermes Automation Blueprints model, any archie-core workflow can be exported as a Hermes blueprint:</p><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">metadata</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> archie</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> blueprint</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> schedule</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;every 6h&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> deliver</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">telegram</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;CI monitor&quot;</span></span></code></pre></div><p>The export produces a <code>SKILL.md</code> with <code>metadata.hermes.blueprint</code> that Hermes can schedule. The blueprint&#39;s prompt is the archie workflow&#39;s quality pipeline.</p><hr><h2 id="_5-comparison-to-existing-systems" tabindex="-1">5. Comparison to Existing Systems <a class="header-anchor" href="#_5-comparison-to-existing-systems" aria-label="Permalink to &quot;5. Comparison to Existing Systems&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Feature</th><th>archie-core</th><th>GitHub Actions</th><th>Dagger</th><th>Taskfile</th><th>devcontainer</th><th>Hermes Skills</th></tr></thead><tbody><tr><td>Language</td><td>YAML</td><td>YAML</td><td>Go/Python/TS</td><td>YAML</td><td>JSON</td><td>Markdown</td></tr><tr><td>Gates</td><td>Named + composable</td><td>Steps in jobs</td><td>Functions</td><td>Tasks</td><td>Lifecycle scripts</td><td>N/A</td></tr><tr><td>Engine abstraction</td><td>First-class</td><td>GitHub only</td><td>Dagger Engine</td><td>Shell only</td><td>None</td><td>Provider</td></tr><tr><td>Skills</td><td>agentskills.io spec</td><td>Composite actions</td><td>Dagger Modules</td><td>Includes</td><td>Features</td><td>SKILL.md</td></tr><tr><td>Worktree isolation</td><td>Built-in</td><td>No</td><td>Containers</td><td>No</td><td>Container</td><td>No</td></tr><tr><td>Blueprint export</td><td>To Hermes cron</td><td>No</td><td>No</td><td>No</td><td>No</td><td>Native</td></tr><tr><td>Multi-engine fallback</td><td>Yes (ordered list)</td><td>No</td><td>No</td><td>No</td><td>No</td><td>Provider config</td></tr><tr><td>Progressive disclosure</td><td>Yes (skill spec)</td><td>No</td><td>No</td><td>No</td><td>Feature metadata</td><td>Yes</td></tr></tbody></table><hr><h2 id="_6-implementation-phases" tabindex="-1">6. Implementation Phases <a class="header-anchor" href="#_6-implementation-phases" aria-label="Permalink to &quot;6. Implementation Phases&quot;">​</a></h2><h3 id="phase-1-core-workflow-file" tabindex="-1">Phase 1: Core workflow file <a class="header-anchor" href="#phase-1-core-workflow-file" aria-label="Permalink to &quot;Phase 1: Core workflow file&quot;">​</a></h3><ul><li><code>archie.yaml</code> parser and schema validation</li><li>Gate runner (test, lint, format, vet)</li><li><code>archie run &lt;command&gt;</code> CLI</li><li>Sandbox Docker integration</li></ul><h3 id="phase-2-skills" tabindex="-1">Phase 2: Skills <a class="header-anchor" href="#phase-2-skills" aria-label="Permalink to &quot;Phase 2: Skills&quot;">​</a></h3><ul><li>SKILL.md discovery and progressive disclosure</li><li>Skill metadata with gate/tool/engine requirements</li><li><code>archie skills list/install/search</code></li></ul><h3 id="phase-3-engine-abstraction" tabindex="-1">Phase 3: Engine abstraction <a class="header-anchor" href="#phase-3-engine-abstraction" aria-label="Permalink to &quot;Phase 3: Engine abstraction&quot;">​</a></h3><ul><li>Engine interface definition</li><li>Claude Code adapter</li><li>Raw LLM adapter</li><li>Engine fallback chain</li></ul><h3 id="phase-4-advanced-features" tabindex="-1">Phase 4: Advanced features <a class="header-anchor" href="#phase-4-advanced-features" aria-label="Permalink to &quot;Phase 4: Advanced features&quot;">​</a></h3><ul><li>Worktree isolation</li><li>Skill chaining (dependency DAG)</li><li>Gate overrides</li><li>Blueprint export</li></ul><h3 id="phase-5-ecosystem" tabindex="-1">Phase 5: Ecosystem <a class="header-anchor" href="#phase-5-ecosystem" aria-label="Permalink to &quot;Phase 5: Ecosystem&quot;">​</a></h3><ul><li>Public skill registry</li><li><code>archie init --skill &lt;name&gt;</code> scaffolding</li><li>Community skill contributions</li></ul><hr><h2 id="_7-open-questions" tabindex="-1">7. Open Questions <a class="header-anchor" href="#_7-open-questions" aria-label="Permalink to &quot;7. Open Questions&quot;">​</a></h2><ol><li><strong>Skill registry hosting:</strong> Self-hosted on git.catlow.cloud, or use agentskills.io?</li><li><strong>Hermes integration:</strong> Should archie-core be a Hermes tool, a Hermes skill, or standalone?</li><li><strong>Budget enforcement:</strong> Per-skill budget vs. per-workflow budget vs. monthly cap?</li><li><strong>Sandbox image building:</strong> Pre-built images vs. Dockerfile in each skill?</li></ol></div></div></main><footer class="VPDocFooter" data-v-81f89caf data-v-1e23d7de><!--[--><!--]--><div class="edit-info" data-v-1e23d7de><!----><div class="last-updated" data-v-1e23d7de><p class="VPLastUpdated" data-v-1e23d7de data-v-864bcbc0>Last updated: <time datetime="2026-07-28T08:46:50.000Z" data-v-864bcbc0></time></p></div></div><!----></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><footer class="VPFooteLine truncated
<script>window.__VP_HASH_MAP__=JSON.parse("{\"architecture_agent-system.md\":\"Coj6mPZw\",\"architecture_configuration.md\":\"BsVGi7ja\",\"architecture_dependencies-and-contracts.md\":\"ByRODJZC\",\"architecture_generated-documentation.md\":\"qELen1k6\",\"architecture_identity.md\":\"CB0DkYo9\",\"architecture_index.md\":\"DJpk2YHf\",\"architecture_messaging-and-work-intake.md\":\"Q7MxXQDB\",\"architecture_migration-decisions.md\":\"oN2eGfag\",\"architecture_organisation.md\":\"mAPb3vCC\",\"architecture_package-review.md\":\"7BZCENBd\",\"architecture_plugins-and-extensions.md\":\"DmzsC2M0\",\"architecture_policy.md\":\"4L33IZiY\",\"architecture_safe-change-and-recovery.md\":\"CdYeF0XF\",\"archive_archie-core-architecture.md\":\"Bqg5-owD\",\"archive_archie-core-skills-prd-v2.md\":\"D3RVdXag\",\"archive_archie-core-skills-prd.md\":\"D1oUBHEN\",\"archive_decisions.md\":\"DkenJ6mD\",\"archive_design.md\":\"BwF1bH5l\",\"archive_prds_multi-agent-collaboration.md\":\"zqWXF3O0\",\"archive_prds_typescript-plugin-engine.md\":\"DBR1GKuy\",\"archive_prds_yaegi-plugin-system.md\":\"V36uzfZI\",\"index.md\":\"BdS51Ijr\",\"prds_01-project-management.md\":\"DEpuIAgg\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Archie\",\"description\":\"Documentation for the Archie personal agent platform.\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/favicon.svg\",\"nav\":[{\"text\":\"Architecture\",\"link\":\"/architecture/\"}],\"sidebar\":{\"/architecture/\":[{\"text\":\"Architecture\",\"items\":[{\"text\":\"Overview\",\"link\":\"/architecture/\"},{\"text\":\"Repository Organisation\",\"link\":\"/architecture/organisation\"},{\"text\":\"Dependencies and Contracts\",\"link\":\"/architecture/dependencies-and-contracts\"},{\"text\":\"Agent System\",\"link\":\"/architecture/agent-system\"},{\"text\":\"Configuration\",\"link\":\"/architecture/configuration\"},{\"text\":\"Identity\",\"link\":\"/architecture/identity\"},{\"text\":\"Messaging and Work Intake\",\"link\":\"/architecture/messaging-and-work-intake\"},{\"text\":\"Plugins and Extensions\",\"link\":\"/architecture/plugins-and-extensions\"},{\"text\":\"Policy System\",\"link\":\"/architecture/policy\"},{\"text\":\"Safe Change and Recovery\",\"link\":\"/architecture/safe-change-and-recovery\"},{\"text\":\"Generated Documentation\",\"link\":\"/architecture/generated-documentation\"},{\"text\":\"Domain and Feature Review Procedure\",\"link\":\"/architecture/package-review\"},{\"text\":\"Migration Decisions\",\"link\":\"/architecture/migration-decisions\"}]}]},\"search\":{\"provider\":\"local\"},\"footer\":{\"message\":\"Built with VitePress.\",\"copyright\":\"Archie\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
</body>
</html>
-26
View File
@@ -1,26 +0,0 @@
<!DOCTYPE html>
<html lang="en-US" dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Archie Design Decisions | Archie</title>
<meta name="description" content="Documentation for the Archie personal agent platform.">
<meta name="generator" content="VitePress v1.6.4">
<link rel="preload stylesheet" href="/assets/style.C4BXn3EN.css" as="style">
<link rel="preload stylesheet" href="/vp-icons.css" as="style">
<script type="module" src="/assets/app.HIbJYLU1.js"></script>
<link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="modulepreload" href="/assets/chunks/theme.B97NJxv0.js">
<link rel="modulepreload" href="/assets/chunks/framework.BWuWLRhz.js">
<link rel="modulepreload" href="/assets/archive_decisions.md.DkenJ6mD.lean.js">
<link rel="icon" href="/favicon.svg">
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
</head>
<body>
<div id="app"><div class="Layout" data-v-cb931ff4><!--[--><!--]--><!--[--><span tabindex="-1" data-v-8ae66126></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-8ae66126>Skip to content</a><!--]--><!----><header class="VPNav" data-v-cb931ff4 data-v-a1925027><div class="VPNavBar" data-v-a1925027 data-v-2840085c><div class="wrapper" data-v-2840085c><div class="container" data-v-2840085c><div class="title" data-v-2840085c><div class="VPNavBarTitle" data-v-2840085c data-v-e7a29354><a class="title" href="/" data-v-e7a29354><!--[--><!--]--><!--[--><img class="VPImage logo" src="/favicon.svg" alt data-v-eec9b196><!--]--><span data-v-e7a29354>Archie</span><!--[--><!--]--></a></div></div><div class="content" data-v-2840085c><div class="content-body" data-v-2840085c><!--[--><!--]--><div class="VPNavBarSearch search" data-v-2840085c><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-2840085c data-v-ded89948><span id="main-nav-aria-label" class="visually-hidden" data-v-ded89948> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/architecture/" tabindex="0" data-v-ded89948 data-v-0a9a3d21><!--[--><span data-v-0a9a3d21>Architecture</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-2840085c data-v-4b074154><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-4b074154 data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-2840085c data-v-6ca47e2f data-v-b980f1c3><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-b980f1c3><span class="vpi-more-horizontal icon" data-v-b980f1c3></span></button><div class="menu" data-v-b980f1c3><div class="VPMenu" data-v-b980f1c3 data-v-a1767133><!----><!--[--><!--[--><!----><div class="group" data-v-6ca47e2f><div class="item appearance" data-v-6ca47e2f><p class="label" data-v-6ca47e2f>Appearance</p><div class="appearance-action" data-v-6ca47e2f><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-6ca47e2f data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-2840085c data-v-3597ebf2><span class="container" data-v-3597ebf2><span class="top" data-v-3597ebf2></span><span class="middle" data-v-3597ebf2></span><span class="bottom" data-v-3597ebf2></span></span></button></div></div></div></div><div class="divider" data-v-2840085c><div class="divider-line" data-v-2840085c></div></div></div><!----></header><div class="VPLocalNav empty fixed" data-v-cb931ff4 data-v-c17e40bf><div class="container" data-v-c17e40bf><!----><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-c17e40bf data-v-88669269><button data-v-88669269>Return to top</button><!----></div></div></div><!----><div class="VPContent" id="VPContent" data-v-cb931ff4 data-v-6a83e20a><div class="VPDoc has-aside" data-v-6a83e20a data-v-81f89caf><!--[--><!--]--><div class="container" data-v-81f89caf><div class="aside" data-v-81f89caf><div class="aside-curtain" data-v-81f89caf></div><div class="aside-container" data-v-81f89caf><div class="aside-content" data-v-81f89caf><div class="VPDocAside" data-v-81f89caf data-v-2f246d4c><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-2f246d4c data-v-b2d618e4><div class="content" data-v-b2d618e4><div class="outline-marker" data-v-b2d618e4></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-b2d618e4>On this page</div><ul class="VPDocOutlineItem root" data-v-b2d618e4 data-v-35c93968><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-2f246d4c></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-81f89caf><div class="content-container" data-v-81f89caf><!-Line truncated
<script>window.__VP_HASH_MAP__=JSON.parse("{\"architecture_agent-system.md\":\"Coj6mPZw\",\"architecture_configuration.md\":\"BsVGi7ja\",\"architecture_dependencies-and-contracts.md\":\"ByRODJZC\",\"architecture_generated-documentation.md\":\"qELen1k6\",\"architecture_identity.md\":\"CB0DkYo9\",\"architecture_index.md\":\"DJpk2YHf\",\"architecture_messaging-and-work-intake.md\":\"Q7MxXQDB\",\"architecture_migration-decisions.md\":\"oN2eGfag\",\"architecture_organisation.md\":\"mAPb3vCC\",\"architecture_package-review.md\":\"7BZCENBd\",\"architecture_plugins-and-extensions.md\":\"DmzsC2M0\",\"architecture_policy.md\":\"4L33IZiY\",\"architecture_safe-change-and-recovery.md\":\"CdYeF0XF\",\"archive_archie-core-architecture.md\":\"Bqg5-owD\",\"archive_archie-core-skills-prd-v2.md\":\"D3RVdXag\",\"archive_archie-core-skills-prd.md\":\"D1oUBHEN\",\"archive_decisions.md\":\"DkenJ6mD\",\"archive_design.md\":\"BwF1bH5l\",\"archive_prds_multi-agent-collaboration.md\":\"zqWXF3O0\",\"archive_prds_typescript-plugin-engine.md\":\"DBR1GKuy\",\"archive_prds_yaegi-plugin-system.md\":\"V36uzfZI\",\"index.md\":\"BdS51Ijr\",\"prds_01-project-management.md\":\"DEpuIAgg\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Archie\",\"description\":\"Documentation for the Archie personal agent platform.\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/favicon.svg\",\"nav\":[{\"text\":\"Architecture\",\"link\":\"/architecture/\"}],\"sidebar\":{\"/architecture/\":[{\"text\":\"Architecture\",\"items\":[{\"text\":\"Overview\",\"link\":\"/architecture/\"},{\"text\":\"Repository Organisation\",\"link\":\"/architecture/organisation\"},{\"text\":\"Dependencies and Contracts\",\"link\":\"/architecture/dependencies-and-contracts\"},{\"text\":\"Agent System\",\"link\":\"/architecture/agent-system\"},{\"text\":\"Configuration\",\"link\":\"/architecture/configuration\"},{\"text\":\"Identity\",\"link\":\"/architecture/identity\"},{\"text\":\"Messaging and Work Intake\",\"link\":\"/architecture/messaging-and-work-intake\"},{\"text\":\"Plugins and Extensions\",\"link\":\"/architecture/plugins-and-extensions\"},{\"text\":\"Policy System\",\"link\":\"/architecture/policy\"},{\"text\":\"Safe Change and Recovery\",\"link\":\"/architecture/safe-change-and-recovery\"},{\"text\":\"Generated Documentation\",\"link\":\"/architecture/generated-documentation\"},{\"text\":\"Domain and Feature Review Procedure\",\"link\":\"/architecture/package-review\"},{\"text\":\"Migration Decisions\",\"link\":\"/architecture/migration-decisions\"}]}]},\"search\":{\"provider\":\"local\"},\"footer\":{\"message\":\"Built with VitePress.\",\"copyright\":\"Archie\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
</body>
</html>
@@ -1,129 +0,0 @@
<!DOCTYPE html>
<html lang="en-US" dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Multi-Agent Collaboration -- PRD | Archie</title>
<meta name="description" content="Documentation for the Archie personal agent platform.">
<meta name="generator" content="VitePress v1.6.4">
<link rel="preload stylesheet" href="/assets/style.C4BXn3EN.css" as="style">
<link rel="preload stylesheet" href="/vp-icons.css" as="style">
<script type="module" src="/assets/app.HIbJYLU1.js"></script>
<link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="modulepreload" href="/assets/chunks/theme.B97NJxv0.js">
<link rel="modulepreload" href="/assets/chunks/framework.BWuWLRhz.js">
<link rel="modulepreload" href="/assets/archive_prds_multi-agent-collaboration.md.zqWXF3O0.lean.js">
<link rel="icon" href="/favicon.svg">
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
</head>
<body>
<div id="app"><div class="Layout" data-v-cb931ff4><!--[--><!--]--><!--[--><span tabindex="-1" data-v-8ae66126></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-8ae66126>Skip to content</a><!--]--><!----><header class="VPNav" data-v-cb931ff4 data-v-a1925027><div class="VPNavBar" data-v-a1925027 data-v-2840085c><div class="wrapper" data-v-2840085c><div class="container" data-v-2840085c><div class="title" data-v-2840085c><div class="VPNavBarTitle" data-v-2840085c data-v-e7a29354><a class="title" href="/" data-v-e7a29354><!--[--><!--]--><!--[--><img class="VPImage logo" src="/favicon.svg" alt data-v-eec9b196><!--]--><span data-v-e7a29354>Archie</span><!--[--><!--]--></a></div></div><div class="content" data-v-2840085c><div class="content-body" data-v-2840085c><!--[--><!--]--><div class="VPNavBarSearch search" data-v-2840085c><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-2840085c data-v-ded89948><span id="main-nav-aria-label" class="visually-hidden" data-v-ded89948> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/architecture/" tabindex="0" data-v-ded89948 data-v-0a9a3d21><!--[--><span data-v-0a9a3d21>Architecture</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-2840085c data-v-4b074154><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-4b074154 data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-2840085c data-v-6ca47e2f data-v-b980f1c3><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-b980f1c3><span class="vpi-more-horizontal icon" data-v-b980f1c3></span></button><div class="menu" data-v-b980f1c3><div class="VPMenu" data-v-b980f1c3 data-v-a1767133><!----><!--[--><!--[--><!----><div class="group" data-v-6ca47e2f><div class="item appearance" data-v-6ca47e2f><p class="label" data-v-6ca47e2f>Appearance</p><div class="appearance-action" data-v-6ca47e2f><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-6ca47e2f data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-2840085c data-v-3597ebf2><span class="container" data-v-3597ebf2><span class="top" data-v-3597ebf2></span><span class="middle" data-v-3597ebf2></span><span class="bottom" data-v-3597ebf2></span></span></button></div></div></div></div><div class="divider" data-v-2840085c><div class="divider-line" data-v-2840085c></div></div></div><!----></header><div class="VPLocalNav empty fixed" data-v-cb931ff4 data-v-c17e40bf><div class="container" data-v-c17e40bf><!----><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-c17e40bf data-v-88669269><button data-v-88669269>Return to top</button><!----></div></div></div><!----><div class="VPContent" id="VPContent" data-v-cb931ff4 data-v-6a83e20a><div class="VPDoc has-aside" data-v-6a83e20a data-v-81f89caf><!--[--><!--]--><div class="container" data-v-81f89caf><div class="aside" data-v-81f89caf><div class="aside-curtain" data-v-81f89caf></div><div class="aside-container" data-v-81f89caf><div class="aside-content" data-v-81f89caf><div class="VPDocAside" data-v-81f89caf data-v-2f246d4c><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-2f246d4c data-v-b2d618e4><div class="content" data-v-b2d618e4><div class="outline-marker" data-v-b2d618e4></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-b2d618e4>On this page</div><ul class="VPDocOutlineItem root" data-v-b2d618e4 data-v-35c93968><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-2f246d4c></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-81f89caf><div class="content-container" data-v-81f89caf><!-Line truncated
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[[</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">identities</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">name = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;archie&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">bot_user = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;archie&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">forge = { type = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;gitea&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, host = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, token_env = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">models = { triage = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, planner = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, builder = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">repos = [ </span><span style="--shiki-light:#B31D28;--shiki-light-font-style:italic;--shiki-dark:#FDAEB7;--shiki-dark-font-style:italic;">... </span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[[</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">identities</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">name = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;winter&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">bot_user = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;winter&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">forge = { type = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;gitea&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, host = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, token_env = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">models = { triage = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, planner = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, builder = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">repos = [ </span><span style="--shiki-light:#B31D28;--shiki-light-font-style:italic;--shiki-dark:#FDAEB7;--shiki-dark-font-style:italic;">... </span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span></code></pre></div><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span></span></span>
<span class="line"><span>**Design answer (2026-07-25): per-identity goroutine, shared infrastructure.**</span></span>
<span class="line"><span></span></span>
<span class="line"><span>Each identity gets its own goroutine running an independent poll loop with</span></span>
<span class="line"><span>its own forge client, worktree manager, and NATS subject namespace</span></span>
<span class="line"><span>(`archie.&lt;identity&gt;.task.&lt;type&gt;`). They share only the infrastructure</span></span>
<span class="line"><span>pieces where isolation adds cost without benefit:</span></span>
<span class="line"><span></span></span>
<span class="line"><span>| Shared (one instance for all identities) | Per-identity (one per goroutine) |</span></span>
<span class="line"><span>|---|---|</span></span>
<span class="line"><span>| SQLite store (`internal/store`) | Forge client (different token per identity) |</span></span>
<span class="line"><span>| NATS connection (`internal/nats`) | Worktree manager (different `BotUser` per identity) |</span></span>
<span class="line"><span>| Container pool (`internal/container`) | Config subset: forge, repos, models, providers, dispatch, poll_interval, bot_user, bot_email |</span></span>
<span class="line"><span>| Event bus (`internal/events`) | NATS subject namespace: `archie.&lt;identity&gt;.task.&lt;type&gt;` |</span></span>
<span class="line"><span>| Web UI (`internal/webui`) | Poll loop goroutine |</span></span>
<span class="line"><span>| Plugin registry (`internal/plugin`) | |</span></span>
<span class="line"><span>| Gateway router (`internal/gateway`) | |</span></span>
<span class="line"><span></span></span>
<span class="line"><span>Decision rationale: per-identity goroutines guarantee failure isolation (one</span></span>
<span class="line"><span>identity&#39;s forge outage cannot block another&#39;s poll tick), each identity</span></span>
<span class="line"><span>gets its own forge rate-limit domain, and the existing `Daemon` struct maps</span></span>
<span class="line"><span>cleanly -- each goroutine holds a thin `Identity` value (forge client + config</span></span>
<span class="line"><span>subset + worktree manager + NATS subject prefix) and dispatches tasks with</span></span>
<span class="line"><span>an `identity_name` column on the task row. The shared NATS connection</span></span>
<span class="line"><span>multiplexes subjects by identity prefix; the shared store already handles</span></span>
<span class="line"><span>concurrent ClaimNext via SQLite&#39;s serialized writes. NATS subjects carry</span></span>
<span class="line"><span>the identity name so agent containers (which consume from NATS) route</span></span>
<span class="line"><span>responses back to the correct daemon identity.</span></span>
<span class="line"><span></span></span>
<span class="line"><span>This design resolves the open question in section 4 of the original PRD</span></span>
<span class="line"><span>draft (per-identity goroutine vs single loop iterating identities -- the</span></span>
<span class="line"><span>former, for failure isolation).</span></span>
<span class="line"><span></span></span>
<span class="line"><span>## 5. Priority / phasing</span></span>
<span class="line"><span></span></span>
<span class="line"><span>Sam deferred ordering to this PRD (interview answer: &quot;let the interview</span></span>
<span class="line"><span>settle scope, I&#39;ll decide after seeing it written up&quot;). Proposed</span></span>
<span class="line"><span>dependency-ordered phases, for Sam to confirm or reorder:</span></span>
<span class="line"><span></span></span>
<span class="line"><span>**Phase A -- Foundation (blocks everything else)**</span></span>
<span class="line"><span>- Wire Layer 2 core plugin loading (`~/.config/archie/plugins/`,</span></span>
<span class="line"><span> `Plugin.Register(daemon)`) into `cmd/archied/main.go`. Currently designed,</span></span>
<span class="line"><span> unwired -- both chat channels and new forges depend on this existing.</span></span>
<span class="line"><span></span></span>
<span class="line"><span>**Phase B -- Multi-identity daemon core**</span></span>
<span class="line"><span>- Replace single `Config.BotUser` with the `[[identities]]` shape (section</span></span>
<span class="line"><span> 4, after design confirmation).</span></span>
<span class="line"><span>- Multi-identity poll/dispatch, still issue-driven (Gitea only, no chat yet).</span></span>
<span class="line"><span>- Migrate the two carina processes (archie, winter) onto one daemon as a</span></span>
<span class="line"><span> real-world validation.</span></span>
<span class="line"><span></span></span>
<span class="line"><span>**Phase C -- Chat channel foundation**</span></span>
<span class="line"><span>- Chat channel plugin interface (parallel to `forge.Forge`).</span></span>
<span class="line"><span>- Telegram channel plugin: read-only Q&amp;A against task/daemon state first,</span></span>
<span class="line"><span> then spawn/control actions gated through the same review pipeline as</span></span>
<span class="line"><span> issue-driven dispatch.</span></span>
<span class="line"><span>- Web UI: extend `internal/webui` from read-only SSE dashboard to</span></span>
<span class="line"><span> bidirectional chat.</span></span>
<span class="line"><span>- Multi-session conversation memory (distinct persistence from per-task</span></span>
<span class="line"><span> `/data/memory.jsonl`).</span></span>
<span class="line"><span>- Slash commands (`/status`, `/spawn`, `/approve`, `/cancel`).</span></span>
<span class="line"><span></span></span>
<span class="line"><span>**Phase D -- Agent-to-agent collaboration**</span></span>
<span class="line"><span>- Plan -&gt; implement -&gt; review handoff within a single task&#39;s workflow</span></span>
<span class="line"><span> (builds on existing `workflow.Stage` sequencing -- this may already be</span></span>
<span class="line"><span> close given the `implement` workflow&#39;s plan/build stage split; needs</span></span>
<span class="line"><span> investigation into how much is genuinely new vs. reframing).</span></span>
<span class="line"><span></span></span>
<span class="line"><span>**Phase E -- Extended integrations (as needed, each is an independent</span></span>
<span class="line"><span>plugin, no fixed order)**</span></span>
<span class="line"><span>- GitLab forge plugin.</span></span>
<span class="line"><span>- MCP client capability (archie consuming external MCP servers as tools).</span></span>
<span class="line"><span>- SSH / remote execution tool.</span></span>
<span class="line"><span>- Additional chat channels.</span></span>
<span class="line"><span>- Multi-user support (identity/session model extended beyond</span></span>
<span class="line"><span> single-operator -- needs its own design pass; not blocking Phase A-D).</span></span>
<span class="line"><span></span></span>
<span class="line"><span>Sam&#39;s explicit instruction was to identify next requirements **and begin</span></span>
<span class="line"><span>work**, not just deliver a document. Phase A (wiring the Layer 2 plugin</span></span>
<span class="line"><span>loader) is the correct starting point: it&#39;s small, well-specified already in</span></span>
<span class="line"><span>`docs/prds/archie-core-v2-architecture.md` sec.5, and unblocks both the chat</span></span>
<span class="line"><span>channel work and new forge plugins that everything else in this PRD depends</span></span>
<span class="line"><span>on.</span></span>
<span class="line"><span></span></span>
<span class="line"><span>## 6. Acceptance criteria for this PRD</span></span>
<span class="line"><span></span></span>
<span class="line"><span>- [x] Reflects Sam&#39;s actual interview answers, not assumptions.</span></span>
<span class="line"><span>- [x] Confirms the archie/winter config diff (repo lists differ, not just</span></span>
<span class="line"><span> identity).</span></span>
<span class="line"><span>- [ ] Broken into scoped, dependency-ordered beads issues under</span></span>
<span class="line"><span> `archie-core-abg`, the way the 5zh epic was. (Next step, this session.)</span></span></code></pre></div></div></div></main><footer class="VPDocFooter" data-v-81f89caf data-v-1e23d7de><!--[--><!--]--><div class="edit-info" data-v-1e23d7de><!----><div class="last-updated" data-v-1e23d7de><p class="VPLastUpdated" data-v-1e23d7de data-v-864bcbc0>Last updated: <time datetime="2026-07-28T08:46:50.000Z" data-v-864bcbc0></time></p></div></div><!----></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><footer class="VPFooter" data-v-cb931ff4 data-v-c113a85a><div class="container" data-v-c113a85a><p class="message" data-v-c113a85a>Built with VitePress.</p><p class="copyright" data-v-c113a85a>Archie</p></div></footer><!--[--><!--]--></div></div>
<script>window.__VP_HASH_MAP__=JSON.parse("{\"architecture_agent-system.md\":\"Coj6mPZw\",\"architecture_configuration.md\":\"BsVGi7ja\",\"architecture_dependencies-and-contracts.md\":\"ByRODJZC\",\"architecture_generated-documentation.md\":\"qELen1k6\",\"architecture_identity.md\":\"CB0DkYo9\",\"architecture_index.md\":\"DJpk2YHf\",\"architecture_messaging-and-work-intake.md\":\"Q7MxXQDB\",\"architecture_migration-decisions.md\":\"oN2eGfag\",\"architecture_organisation.md\":\"mAPb3vCC\",\"architecture_package-review.md\":\"7BZCENBd\",\"architecture_plugins-and-extensions.md\":\"DmzsC2M0\",\"architecture_policy.md\":\"4L33IZiY\",\"architecture_safe-change-and-recovery.md\":\"CdYeF0XF\",\"archive_archie-core-architecture.md\":\"Bqg5-owD\",\"archive_archie-core-skills-prd-v2.md\":\"D3RVdXag\",\"archive_archie-core-skills-prd.md\":\"D1oUBHEN\",\"archive_decisions.md\":\"DkenJ6mD\",\"archive_design.md\":\"BwF1bH5l\",\"archive_prds_multi-agent-collaboration.md\":\"zqWXF3O0\",\"archive_prds_typescript-plugin-engine.md\":\"DBR1GKuy\",\"archive_prds_yaegi-plugin-system.md\":\"V36uzfZI\",\"index.md\":\"BdS51Ijr\",\"prds_01-project-management.md\":\"DEpuIAgg\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Archie\",\"description\":\"Documentation for the Archie personal agent platform.\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/favicon.svg\",\"nav\":[{\"text\":\"Architecture\",\"link\":\"/architecture/\"}],\"sidebar\":{\"/architecture/\":[{\"text\":\"Architecture\",\"items\":[{\"text\":\"Overview\",\"link\":\"/architecture/\"},{\"text\":\"Repository Organisation\",\"link\":\"/architecture/organisation\"},{\"text\":\"Dependencies and Contracts\",\"link\":\"/architecture/dependencies-and-contracts\"},{\"text\":\"Agent System\",\"link\":\"/architecture/agent-system\"},{\"text\":\"Configuration\",\"link\":\"/architecture/configuration\"},{\"text\":\"Identity\",\"link\":\"/architecture/identity\"},{\"text\":\"Messaging and Work Intake\",\"link\":\"/architecture/messaging-and-work-intake\"},{\"text\":\"Plugins and Extensions\",\"link\":\"/architecture/plugins-and-extensions\"},{\"text\":\"Policy System\",\"link\":\"/architecture/policy\"},{\"text\":\"Safe Change and Recovery\",\"link\":\"/architecture/safe-change-and-recovery\"},{\"text\":\"Generated Documentation\",\"link\":\"/architecture/generated-documentation\"},{\"text\":\"Domain and Feature Review Procedure\",\"link\":\"/architecture/package-review\"},{\"text\":\"Migration Decisions\",\"link\":\"/architecture/migration-decisions\"}]}]},\"search\":{\"provider\":\"local\"},\"footer\":{\"message\":\"Built with VitePress.\",\"copyright\":\"Archie\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
</body>
</html>
@@ -1,238 +0,0 @@
<!DOCTYPE html>
<html lang="en-US" dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>archie-core TypeScript Plugin Engine -- PRD | Archie</title>
<meta name="description" content="Documentation for the Archie personal agent platform.">
<meta name="generator" content="VitePress v1.6.4">
<link rel="preload stylesheet" href="/assets/style.C4BXn3EN.css" as="style">
<link rel="preload stylesheet" href="/vp-icons.css" as="style">
<script type="module" src="/assets/app.HIbJYLU1.js"></script>
<link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="modulepreload" href="/assets/chunks/theme.B97NJxv0.js">
<link rel="modulepreload" href="/assets/chunks/framework.BWuWLRhz.js">
<link rel="modulepreload" href="/assets/archive_prds_typescript-plugin-engine.md.DBR1GKuy.lean.js">
<link rel="icon" href="/favicon.svg">
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
</head>
<body>
<div id="app"><div class="Layout" data-v-cb931ff4><!--[--><!--]--><!--[--><span tabindex="-1" data-v-8ae66126></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-8ae66126>Skip to content</a><!--]--><!----><header class="VPNav" data-v-cb931ff4 data-v-a1925027><div class="VPNavBar" data-v-a1925027 data-v-2840085c><div class="wrapper" data-v-2840085c><div class="container" data-v-2840085c><div class="title" data-v-2840085c><div class="VPNavBarTitle" data-v-2840085c data-v-e7a29354><a class="title" href="/" data-v-e7a29354><!--[--><!--]--><!--[--><img class="VPImage logo" src="/favicon.svg" alt data-v-eec9b196><!--]--><span data-v-e7a29354>Archie</span><!--[--><!--]--></a></div></div><div class="content" data-v-2840085c><div class="content-body" data-v-2840085c><!--[--><!--]--><div class="VPNavBarSearch search" data-v-2840085c><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-2840085c data-v-ded89948><span id="main-nav-aria-label" class="visually-hidden" data-v-ded89948> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/architecture/" tabindex="0" data-v-ded89948 data-v-0a9a3d21><!--[--><span data-v-0a9a3d21>Architecture</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-2840085c data-v-4b074154><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-4b074154 data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-2840085c data-v-6ca47e2f data-v-b980f1c3><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-b980f1c3><span class="vpi-more-horizontal icon" data-v-b980f1c3></span></button><div class="menu" data-v-b980f1c3><div class="VPMenu" data-v-b980f1c3 data-v-a1767133><!----><!--[--><!--[--><!----><div class="group" data-v-6ca47e2f><div class="item appearance" data-v-6ca47e2f><p class="label" data-v-6ca47e2f>Appearance</p><div class="appearance-action" data-v-6ca47e2f><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-6ca47e2f data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-2840085c data-v-3597ebf2><span class="container" data-v-3597ebf2><span class="top" data-v-3597ebf2></span><span class="middle" data-v-3597ebf2></span><span class="bottom" data-v-3597ebf2></span></span></button></div></div></div></div><div class="divider" data-v-2840085c><div class="divider-line" data-v-2840085c></div></div></div><!----></header><div class="VPLocalNav empty fixed" data-v-cb931ff4 data-v-c17e40bf><div class="container" data-v-c17e40bf><!----><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-c17e40bf data-v-88669269><button data-v-88669269>Return to top</button><!----></div></div></div><!----><div class="VPContent" id="VPContent" data-v-cb931ff4 data-v-6a83e20a><div class="VPDoc has-aside" data-v-6a83e20a data-v-81f89caf><!--[--><!--]--><div class="container" data-v-81f89caf><div class="aside" data-v-81f89caf><div class="aside-curtain" data-v-81f89caf></div><div class="aside-container" data-v-81f89caf><div class="aside-content" data-v-81f89caf><div class="VPDocAside" data-v-81f89caf data-v-2f246d4c><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-2f246d4c data-v-b2d618e4><div class="content" data-v-b2d618e4><div class="outline-marker" data-v-b2d618e4></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-b2d618e4>On this page</div><ul class="VPDocOutlineItem root" data-v-b2d618e4 data-v-35c93968><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-2f246d4c></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-81f89caf><div class="content-container" data-v-81f89caf><!-Line truncated
<span class="line"><span>├── custom-gate.ts # gate functions: exported `check()` </span></span>
<span class="line"><span>├── db-migration.ts # custom stage: exported `stage()`</span></span>
<span class="line"><span>└── notify-slack.ts # skill script: exported `run()`</span></span></code></pre></div><p>Each file is a self-contained module. No <code>package.json</code>, no <code>node_modules</code>, no external imports. If you need external deps, they need to be exposed via archie-core&#39;s Go→JS bridge.</p><h3 id="plugin-types" tabindex="-1">Plugin types <a class="header-anchor" href="#plugin-types" aria-label="Permalink to &quot;Plugin types&quot;">​</a></h3><p>A plugin declares its role via an exported symbol:</p><table tabindex="0"><thead><tr><th>Export</th><th>Role</th><th>When called</th></tr></thead><tbody><tr><td><code>export function check(ctx: GateContext): Finding[]</code></td><td>Gate function</td><td>After shell-based gate, before commit</td></tr><tr><td><code>export function stage(): Stage</code></td><td>Workflow stage</td><td>When a workflow references the stage name</td></tr><tr><td><code>export function run(ctx: ScriptContext): void</code></td><td>Skill script</td><td>When a skill&#39;s instructions invoke the script</td></tr></tbody></table><p>arcie-core discovers the role by checking which exports exist. A file can export multiple roles.</p><h3 id="gate-functions" tabindex="-1">Gate functions <a class="header-anchor" href="#gate-functions" aria-label="Permalink to &quot;Gate functions&quot;">​</a></h3><div class="language-typescript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">typescript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// .archie/workflows/custom-gate.ts</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">interface</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> GateContext</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> diff</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// unified diff of changes</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> changedFiles</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[]; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// list of changed file paths</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> dir</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// absolute worktree path</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> repo</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// &quot;owner/name&quot;</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> baseRef</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// &quot;origin/main&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">interface</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Finding</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> level</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;error&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;warn&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> file</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> line</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> number</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> message</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">interface</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Block</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> name</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> message</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> function</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> check</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> GateContext</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Finding</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[] {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> findings</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Finding</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[] </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [];</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Rule: no new panic() calls</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> for</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> line</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> of</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.diff.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">split</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\n</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)) {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (line.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">startsWith</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;+&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&amp;&amp;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> !</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">line.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">startsWith</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;+++&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)) {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (line.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">includes</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;panic(&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)) {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> findings.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">push</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> level: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;error&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> message: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;new panic() call -- use error returns instead&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Rule: no time.Sleep in non-test files</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> for</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> file</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> of</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.changedFiles) {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (file.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">endsWith</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;_test.go&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">continue</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> content</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> archie.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">readFile</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">`${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ctx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}/${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">file</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (content.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">includes</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;time.Sleep&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)) {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> findings.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">push</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> level: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;warn&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> file: file,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> message: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;time.Sleep in non-test code -- use time.Ticker instead&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> findings;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>After transpilation and execution, archie-core calls <code>check(ctx)</code> via goja. Error-level findings park the task. Warn-level findings are logged.</p><h3 id="custom-workflow-stages" tabindex="-1">Custom workflow stages <a class="header-anchor" href="#custom-workflow-stages" aria-label="Permalink to &quot;Custom workflow stages&quot;">​</a></h3><div class="language-typescript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">typescript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// .archie/workflows/run-migrations.ts</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> function</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> stage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">()</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Stage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> name: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;db-migration&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> TaskContext</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Check if migrations directory exists</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> hasMigrations</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> archie.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">fileExists</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">`${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ctx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}/migrations`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">hasMigrations) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// nothing to do</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Run migration tests</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> result</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> archie.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">exec</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;go&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;test&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;./migrations/...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]);</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (result.exitCode </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!==</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 0</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> `migration tests failed: ${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">result</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">stderr</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// success</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> };</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="skill-scripts" tabindex="-1">Skill scripts <a class="header-anchor" href="#skill-scripts" aria-label="Permalink to &quot;Skill scripts&quot;">​</a></h3><div class="language-typescript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">typescript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// .archie/workflows/security-audit.ts</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> function</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> ScriptContext</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> void</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> result</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> archie.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">exec</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;gitleaks&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;detect&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;--no-git&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]);</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (result.exitCode </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!==</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 0</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> archie.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">log</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;warn&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">`gitleaks found secrets:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\n</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">result</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">stdout</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> archie.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">log</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;info&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;security audit complete&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="archie-go→js-bridge" tabindex="-1">archie Go→JS bridge <a class="header-anchor" href="#archie-go→js-bridge" aria-label="Permalink to &quot;archie Go→JS bridge&quot;">​</a></h3><p>arcie-core exposes a <code>archie</code> global in the goja runtime:</p><div class="language-typescript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">typescript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">interface</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Archie</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // File operations (scoped to worktree)</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> readFile</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">path</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> fileExists</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">path</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> boolean</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> listDir</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">path</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[];</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> walkDir</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">path</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[];</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> </span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Shell execution</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> exec</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">command</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">args</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[])</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> ExecResult</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> </span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Logging</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> log</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">level</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">message</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> void</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> </span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Path utilities</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> resolve</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">...</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">parts</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[])</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> ext</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">path</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> </span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Environment</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> env</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">key</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> </span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // HTTP (optional, gated)</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> fetch</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">url</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">options</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> FetchOptions</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> FetchResult</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">interface</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> ExecResult</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> stdout</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> stderr</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> exitCode</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> number</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>All file operations are <strong>jailed to the worktree</strong>. <code>archie.readFile(&quot;/etc/passwd&quot;)</code> fails. The bridge enforces this in Go before passing the path to the OS.</p><h3 id="reload-cycle" tabindex="-1">Reload cycle <a class="header-anchor" href="#reload-cycle" aria-label="Permalink to &quot;Reload cycle&quot;">​</a></h3><p>Plugins are loaded fresh on every poll cycle -- archie-core already fresh-clones per task. No hot-reload complexity, no cache invalidation. The worktree is the source of truth.</p><p>For the rare case where a plugin errors at parse/transpile time, archie-core comments on the issue with the diagnostic and parks the task. The plugin author fixes the <code>.ts</code> file and requeues.</p><hr><h2 id="implementation" tabindex="-1">Implementation <a class="header-anchor" href="#implementation" aria-label="Permalink to &quot;Implementation&quot;">​</a></h2><h3 id="architecture" tabindex="-1">Architecture <a class="header-anchor" href="#architecture" aria-label="Permalink to &quot;Architecture&quot;">​</a></h3><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>internal/plugins/</span></span>
<span class="line"><span>├── loader.go # scan .archie/workflows/, transpile, evaluate</span></span>
<span class="line"><span>├── runtime.go # goja runtime pool management</span></span>
<span class="line"><span>├── bridge.go # archie global (file I/O, exec, log, fetch)</span></span>
<span class="line"><span>├── types.go # GateContext, Finding, Stage, TaskContext → JS types</span></span>
<span class="line"><span>├── loader_test.go</span></span>
<span class="line"><span>└── testdata/</span></span>
<span class="line"><span> └── workflows/</span></span>
<span class="line"><span> ├── gate.ts # test gate plugin</span></span>
<span class="line"><span> └── stage.ts # test stage plugin</span></span></code></pre></div><h3 id="goja-runtime-pool" tabindex="-1">goja runtime pool <a class="header-anchor" href="#goja-runtime-pool" aria-label="Permalink to &quot;goja runtime pool&quot;">​</a></h3><p>Workflow stages and gates need a clean goja runtime per execution. Creating a new runtime per call is slow (~50ms for stdlib setup). A pool of pre-warmed runtimes solves this:</p><div class="language-go vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">go</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">type</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Pool</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> struct</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> warm </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">chan</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> *</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">goja</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Runtime</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">func</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> NewPool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">size</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> int</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">*</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Pool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> p </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &amp;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Pool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{warm: </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">make</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">chan</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> *</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">goja</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Runtime</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, size)}</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> for</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> i </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 0</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; i </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> size; i</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">++</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> rt </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> goja.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">New</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">()</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> installBridge</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(rt) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// register the `archie` global</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> installStdlib</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(rt) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// console, setTimeout, etc.</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> p.warm </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> rt</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> p</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">func</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">p </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">*</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Pool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> context</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Context</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">src</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">globals</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> map</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">any</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) (</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">goja</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Value</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">error</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> rt </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">p.warm</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> defer</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> func</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() { p.warm </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> rt }()</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Set per-execution globals</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> for</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> k, v </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> range</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> globals {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> rt.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Set</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(k, v)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> rt.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">RunString</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(src)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="transpile-pipeline" tabindex="-1">Transpile pipeline <a class="header-anchor" href="#transpile-pipeline" aria-label="Permalink to &quot;Transpile pipeline&quot;">​</a></h3><div class="language-go vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">go</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">func</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">l </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">*</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Loader</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">transpile</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">filename</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ts</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> []</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">byte</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) (</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">error</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> result </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> l.esbuild.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Transform</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(ts), </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">api</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">TransformOptions</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Loader: api.LoaderTS,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Target: api.ES2017,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Sourcefile: filename,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> })</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> len</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(result.Errors) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 0</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, fmt.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Errorf</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;transpile </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">%s</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">%v</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, filename, result.Errors)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(result.Code), </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">nil</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="load-pipeline" tabindex="-1">load pipeline <a class="header-anchor" href="#load-pipeline" aria-label="Permalink to &quot;load pipeline&quot;">​</a></h3><div class="language-go vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">go</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">func</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">l </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">*</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Loader</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">LoadPlugins</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">worktreeDir</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) ([]</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Plugin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">error</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> filepath.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Join</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(worktreeDir, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;.archie&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;workflows&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> entries, err </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> os.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">ReadDir</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(dir)</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> os.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">IsNotExist</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(err) {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">nil</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // no plugins -- not an error</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> err </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, err</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> var</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> plugins []</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Plugin</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> for</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> _, e </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> range</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> entries {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> !</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">strings.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">HasSuffix</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(e.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(), </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;.ts&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> continue</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> path </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> filepath.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Join</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(dir, e.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">())</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> src, err </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> os.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">ReadFile</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(path)</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> err </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> continue</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> js, err </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> l.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">transpile</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(e.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(), src)</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> err </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> l.log.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Warn</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;plugin transpile failed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;file&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, e.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(), </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;err&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, err)</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> continue</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> rt </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> l.pool.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Acquire</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">()</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> _, err </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> rt.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">RunString</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(js)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> l.pool.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Release</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(rt)</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> err </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> l.log.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Warn</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;plugin eval failed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;file&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, e.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(), </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;err&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, err)</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> continue</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> plugins </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> append</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(plugins, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">discover</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(rt, e.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">())</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">...</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> plugins, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">nil</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="export-discovery" tabindex="-1">Export discovery <a class="header-anchor" href="#export-discovery" aria-label="Permalink to &quot;Export discovery&quot;">​</a></h3><div class="language-go vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">go</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">func</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> discover</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">rt</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> *</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">goja</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Runtime</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">filename</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) []</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Plugin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> var</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> out []</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Plugin</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> check </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> rt.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Get</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;check&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">); check </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> out </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> append</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(out, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Plugin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{Kind: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;gate&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, Name: filename, Func: check})</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> stage </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> rt.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Get</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;stage&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">); stage </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> out </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> append</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(out, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Plugin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{Kind: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;stage&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, Name: filename, Func: stage})</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> run </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> rt.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Get</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;run&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">); run </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> out </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> append</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(out, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Plugin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{Kind: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;script&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, Name: filename, Func: run})</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> out</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="wiring-into-the-daemon" tabindex="-1">Wiring into the daemon <a class="header-anchor" href="#wiring-into-the-daemon" aria-label="Permalink to &quot;Wiring into the daemon&quot;">​</a></h3><p>In <code>daemon.process()</code>:</p><div class="language-go vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">go</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// After worktree prepare, before gate stage:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">plugins, err </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> d.Plugins.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">LoadPlugins</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(tc.Dir)</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> err </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> d.Log.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Warn</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;plugin load failed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;err&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, err)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">tc.Plugins </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> plugins </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// available to all stages via TaskContext</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// In the gate stage:</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> gatePlugin </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> tc.Plugins.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Gate</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(); gatePlugin </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> findings </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> callGatePlugin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(gatePlugin, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">gateContext</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(tc))</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> for</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> _, f </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> range</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> findings {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> f.Level </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">==</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;error&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // park the task</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><hr><h2 id="limitations" tabindex="-1">Limitations <a class="header-anchor" href="#limitations" aria-label="Permalink to &quot;Limitations&quot;">​</a></h2><h3 id="goja-s-ecmascript-coverage" tabindex="-1">goja&#39;s ECMAScript coverage <a class="header-anchor" href="#goja-s-ecmascript-coverage" aria-label="Permalink to &quot;goja&#39;s ECMAScript coverage&quot;">​</a></h3><p>goja natively supports ES5.1 with significant ES6 features. Modern syntax like <code>async/await</code>, <code>??</code>, <code>?.</code>, or <code>class</code> fields may not parse. The transpile step (esbuild targeting ES2017) handles most of this, but there will be edge cases:</p><table tabindex="0"><thead><tr><th>Feature</th><th>Status</th></tr></thead><tbody><tr><td>Arrow functions</td><td>✅ via transpile</td></tr><tr><td>Template literals</td><td>✅ via transpile</td></tr><tr><td>Destructuring</td><td>✅ via transpile</td></tr><tr><td><code>const</code>/<code>let</code></td><td>✅ via transpile</td></tr><tr><td><code>async/await</code></td><td>❌ not supported (goja is synchronous)</td></tr><tr><td><code>Promise</code></td><td>❌ requires <code>goja_nodejs</code> event loop</td></tr><tr><td>Generators</td><td>❌ not supported</td></tr><tr><td><code>Proxy</code></td><td>❌ not supported</td></tr></tbody></table><p>For gate scripts, this is fine -- gates are synchronous by nature. If async is genuinely needed later, the Bun backend (via <code>tsgo</code>) is the escape hatch.</p><h3 id="performance" tabindex="-1">Performance <a class="header-anchor" href="#performance" aria-label="Permalink to &quot;Performance&quot;">​</a></h3><p>Gate scripts run once per task. Even a 100ms transpile+eval overhead is negligible compared to the LLM calls in the workflow. If a plugin becomes hot-path, it should be promoted to a compiled Go stage.</p><h3 id="no-external-imports" tabindex="-1">No external imports <a class="header-anchor" href="#no-external-imports" aria-label="Permalink to &quot;No external imports&quot;">​</a></h3><p>Plugins can&#39;t <code>import</code> from npm or other files. They&#39;re self-contained modules. Complexity that needs external deps should be a compiled Go stage, not a plugin. The <code>archie</code> global provides filesystem and shell access, which covers the common cases.</p><hr><h2 id="comparison-yaegi-vs-goja" tabindex="-1">Comparison: Yaegi vs goja <a class="header-anchor" href="#comparison-yaegi-vs-goja" aria-label="Permalink to &quot;Comparison: Yaegi vs goja&quot;">​</a></h2><table tabindex="0"><thead><tr><th></th><th>Yaegi (Go)</th><th>goja + esbuild (TypeScript)</th></tr></thead><tbody><tr><td><strong>Language</strong></td><td>Go</td><td>TypeScript</td></tr><tr><td><strong>Pure Go</strong></td><td>✅</td><td>✅ (goja + esbuild both pure Go)</td></tr><tr><td><strong>CGO</strong></td><td>None</td><td>None</td></tr><tr><td><strong>Transpile step</strong></td><td>None (interpreted directly)</td><td>esbuild TS→JS (~3ms)</td></tr><tr><td><strong>Author audience</strong></td><td>Go developers</td><td>Anyone who knows TypeScript</td></tr><tr><td><strong>Type annotations</strong></td><td>N/A (Go is typed)</td><td>Stripped by esbuild (no type-check at runtime)</td></tr><tr><td><strong>Interop</strong></td><td>Direct Go↔Go via <code>Use()</code></td><td>Bridge via <code>archie</code> global</td></tr><tr><td><strong>Performance</strong></td><td>Interpreted Go (~10x slower than compiled)</td><td>Interpreted JS (~50x slower than V8, fine for gates)</td></tr><tr><td><strong>Maturity</strong></td><td>8k stars, used by Traefik for plugins</td><td>7k stars, used by k6, goja is battle-tested</td></tr><tr><td><strong>File extension</strong></td><td><code>.go</code></td><td><code>.ts</code></td></tr><tr><td><strong>Plugin folder</strong></td><td><code>.archie/workflows/</code></td><td><code>.archie/workflows/</code></td></tr><tr><td><strong>Best for</strong></td><td>Custom stages needing Go&#39;s stdlib, tight daemon integration</td><td>Custom gates and scripts where author familiarity matters</td></tr></tbody></table><p><strong>Recommendation: support both.</strong> They solve different problems. Yaegi for repo owners who want full Go power in their custom stages. goja for repo owners who want to write gates and scripts in TypeScript. Both load from <code>.archie/workflows/</code> -- archie-core discovers which engine to use by file extension (<code>.go</code> → Yaegi, <code>.ts</code> → goja+esbuild).</p><hr><h2 id="implementation-phases" tabindex="-1">Implementation phases <a class="header-anchor" href="#implementation-phases" aria-label="Permalink to &quot;Implementation phases&quot;">​</a></h2><h3 id="phase-1-goja-runtime-esbuild" tabindex="-1">Phase 1: goja runtime + esbuild <a class="header-anchor" href="#phase-1-goja-runtime-esbuild" aria-label="Permalink to &quot;Phase 1: goja Line truncated
<script>window.__VP_HASH_MAP__=JSON.parse("{\"architecture_agent-system.md\":\"Coj6mPZw\",\"architecture_configuration.md\":\"BsVGi7ja\",\"architecture_dependencies-and-contracts.md\":\"ByRODJZC\",\"architecture_generated-documentation.md\":\"qELen1k6\",\"architecture_identity.md\":\"CB0DkYo9\",\"architecture_index.md\":\"DJpk2YHf\",\"architecture_messaging-and-work-intake.md\":\"Q7MxXQDB\",\"architecture_migration-decisions.md\":\"oN2eGfag\",\"architecture_organisation.md\":\"mAPb3vCC\",\"architecture_package-review.md\":\"7BZCENBd\",\"architecture_plugins-and-extensions.md\":\"DmzsC2M0\",\"architecture_policy.md\":\"4L33IZiY\",\"architecture_safe-change-and-recovery.md\":\"CdYeF0XF\",\"archive_archie-core-architecture.md\":\"Bqg5-owD\",\"archive_archie-core-skills-prd-v2.md\":\"D3RVdXag\",\"archive_archie-core-skills-prd.md\":\"D1oUBHEN\",\"archive_decisions.md\":\"DkenJ6mD\",\"archive_design.md\":\"BwF1bH5l\",\"archive_prds_multi-agent-collaboration.md\":\"zqWXF3O0\",\"archive_prds_typescript-plugin-engine.md\":\"DBR1GKuy\",\"archive_prds_yaegi-plugin-system.md\":\"V36uzfZI\",\"index.md\":\"BdS51Ijr\",\"prds_01-project-management.md\":\"DEpuIAgg\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Archie\",\"description\":\"Documentation for the Archie personal agent platform.\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/favicon.svg\",\"nav\":[{\"text\":\"Architecture\",\"link\":\"/architecture/\"}],\"sidebar\":{\"/architecture/\":[{\"text\":\"Architecture\",\"items\":[{\"text\":\"Overview\",\"link\":\"/architecture/\"},{\"text\":\"Repository Organisation\",\"link\":\"/architecture/organisation\"},{\"text\":\"Dependencies and Contracts\",\"link\":\"/architecture/dependencies-and-contracts\"},{\"text\":\"Agent System\",\"link\":\"/architecture/agent-system\"},{\"text\":\"Configuration\",\"link\":\"/architecture/configuration\"},{\"text\":\"Identity\",\"link\":\"/architecture/identity\"},{\"text\":\"Messaging and Work Intake\",\"link\":\"/architecture/messaging-and-work-intake\"},{\"text\":\"Plugins and Extensions\",\"link\":\"/architecture/plugins-and-extensions\"},{\"text\":\"Policy System\",\"link\":\"/architecture/policy\"},{\"text\":\"Safe Change and Recovery\",\"link\":\"/architecture/safe-change-and-recovery\"},{\"text\":\"Generated Documentation\",\"link\":\"/architecture/generated-documentation\"},{\"text\":\"Domain and Feature Review Procedure\",\"link\":\"/architecture/package-review\"},{\"text\":\"Migration Decisions\",\"link\":\"/architecture/migration-decisions\"}]}]},\"search\":{\"provider\":\"local\"},\"footer\":{\"message\":\"Built with VitePress.\",\"copyright\":\"Archie\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
</body>
</html>
@@ -1,127 +0,0 @@
<!DOCTYPE html>
<html lang="en-US" dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>archie-core Yaegi Plugin System -- PRD | Archie</title>
<meta name="description" content="Documentation for the Archie personal agent platform.">
<meta name="generator" content="VitePress v1.6.4">
<link rel="preload stylesheet" href="/assets/style.C4BXn3EN.css" as="style">
<link rel="preload stylesheet" href="/vp-icons.css" as="style">
<script type="module" src="/assets/app.HIbJYLU1.js"></script>
<link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="modulepreload" href="/assets/chunks/theme.B97NJxv0.js">
<link rel="modulepreload" href="/assets/chunks/framework.BWuWLRhz.js">
<link rel="modulepreload" href="/assets/archive_prds_yaegi-plugin-system.md.V36uzfZI.lean.js">
<link rel="icon" href="/favicon.svg">
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
</head>
<body>
<div id="app"><div class="Layout" data-v-cb931ff4><!--[--><!--]--><!--[--><span tabindex="-1" data-v-8ae66126></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-8ae66126>Skip to content</a><!--]--><!----><header class="VPNav" data-v-cb931ff4 data-v-a1925027><div class="VPNavBar" data-v-a1925027 data-v-2840085c><div class="wrapper" data-v-2840085c><div class="container" data-v-2840085c><div class="title" data-v-2840085c><div class="VPNavBarTitle" data-v-2840085c data-v-e7a29354><a class="title" href="/" data-v-e7a29354><!--[--><!--]--><!--[--><img class="VPImage logo" src="/favicon.svg" alt data-v-eec9b196><!--]--><span data-v-e7a29354>Archie</span><!--[--><!--]--></a></div></div><div class="content" data-v-2840085c><div class="content-body" data-v-2840085c><!--[--><!--]--><div class="VPNavBarSearch search" data-v-2840085c><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-2840085c data-v-ded89948><span id="main-nav-aria-label" class="visually-hidden" data-v-ded89948> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/architecture/" tabindex="0" data-v-ded89948 data-v-0a9a3d21><!--[--><span data-v-0a9a3d21>Architecture</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-2840085c data-v-4b074154><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-4b074154 data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-2840085c data-v-6ca47e2f data-v-b980f1c3><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-b980f1c3><span class="vpi-more-horizontal icon" data-v-b980f1c3></span></button><div class="menu" data-v-b980f1c3><div class="VPMenu" data-v-b980f1c3 data-v-a1767133><!----><!--[--><!--[--><!----><div class="group" data-v-6ca47e2f><div class="item appearance" data-v-6ca47e2f><p class="label" data-v-6ca47e2f>Appearance</p><div class="appearance-action" data-v-6ca47e2f><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-6ca47e2f data-v-b2628459 data-v-ff9d0e20><span class="check" data-v-ff9d0e20><span class="icon" data-v-ff9d0e20><!--[--><span class="vpi-sun sun" data-v-b2628459></span><span class="vpi-moon moon" data-v-b2628459></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-2840085c data-v-3597ebf2><span class="container" data-v-3597ebf2><span class="top" data-v-3597ebf2></span><span class="middle" data-v-3597ebf2></span><span class="bottom" data-v-3597ebf2></span></span></button></div></div></div></div><div class="divider" data-v-2840085c><div class="divider-line" data-v-2840085c></div></div></div><!----></header><div class="VPLocalNav empty fixed" data-v-cb931ff4 data-v-c17e40bf><div class="container" data-v-c17e40bf><!----><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-c17e40bf data-v-88669269><button data-v-88669269>Return to top</button><!----></div></div></div><!----><div class="VPContent" id="VPContent" data-v-cb931ff4 data-v-6a83e20a><div class="VPDoc has-aside" data-v-6a83e20a data-v-81f89caf><!--[--><!--]--><div class="container" data-v-81f89caf><div class="aside" data-v-81f89caf><div class="aside-curtain" data-v-81f89caf></div><div class="aside-container" data-v-81f89caf><div class="aside-content" data-v-81f89caf><div class="VPDocAside" data-v-81f89caf data-v-2f246d4c><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-2f246d4c data-v-b2d618e4><div class="content" data-v-b2d618e4><div class="outline-marker" data-v-b2d618e4></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-b2d618e4>On this page</div><ul class="VPDocOutlineItem root" data-v-b2d618e4 data-v-35c93968><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-2f246d4c></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-81f89caf><div class="content-container" data-v-81f89caf><!-Line truncated
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">package</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> gate</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">fmt</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">os</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">path/filepath</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">strings</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// GateContext carries everything the gate checker can inspect.</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">type</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> GateContext</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> struct</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Diff </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // unified diff of all changes</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ChangedFiles []</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // list of changed file paths (repo-relative)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // absolute worktree path</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> BaseRef </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // base branch (e.g. &quot;origin/main&quot;)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Repo </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // &quot;owner/name&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Finding is one gate violation.</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">type</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Finding</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> struct</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Level </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // &quot;error&quot; (blocks commit) or &quot;warn&quot; (advisory)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> File </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // optional file path</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Line </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">int</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // optional line number</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Message </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Block defines a named rule that can prevent passing.</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">type</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Block</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> struct</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Name </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Message </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Check returns findings for the gate. Return nil for a clean gate.</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">func</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Check</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> GateContext</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) []</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Finding</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> var</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> findings []</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Finding</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Rule: no new panic() calls in committed code</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> for</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> _, line </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> range</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> strings.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Split</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(ctx.Diff, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\n</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> strings.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">HasPrefix</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(line, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;+&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&amp;&amp;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> !</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">strings.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">HasPrefix</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(line, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;+++&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> strings.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Contains</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(line, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;panic(&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> findings </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> append</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(findings, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Finding</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Level: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;error&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Message: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;new panic() call -- use error returns instead&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> })</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Rule: no time.Sleep in non-test files</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> for</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> _, f </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> range</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.ChangedFiles {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> strings.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">HasSuffix</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(f, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;_test.go&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> continue</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> path </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> filepath.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Join</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(ctx.Dir, f)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> b, err </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> os.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">ReadFile</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(path)</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> err </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> continue</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> strings.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Contains</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(b), </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;time.Sleep&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> findings </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> append</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(findings, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Finding</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Level: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;warn&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> File: f,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Message: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;time.Sleep in non-test code -- use time.Ticker or context.WithTimeout instead&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> })</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> findings</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>The daemon:</p><ol><li>Reads <code>.archie/gate.go</code> from the worktree</li><li>Creates a Yaegi interpreter with <code>GateContext</code> and <code>Finding</code> types pre-loaded via <code>Use()</code></li><li>Evaluates the file</li><li>Calls <code>Check(ctx)</code> via <code>Eval(&quot;gate.Check&quot;)</code> + <code>Interface()</code></li><li>Logs findings and blocks the gate if any have <code>Level: &quot;error&quot;</code></li></ol><h3 id="custom-workflow-stages-archie-stages" tabindex="-1">Custom workflow stages (<code>.archie/stages/</code>) <a class="header-anchor" href="#custom-workflow-stages-archie-stages" aria-label="Permalink to &quot;Custom workflow stages (`.archie/stages/`)&quot;">​</a></h3><p>A repo can define custom pipeline stages that archie-core discovers and makes routable:</p><div class="language-go vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">go</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// .archie/stages/run-migrations.go</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">package</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> stages</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">github.com/samcharles93/archie-core/internal/workflow</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">func</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Stage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">workflow</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Stage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> workflow</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Stage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Name: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;db-migration&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Run: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">func</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> context</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Context</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">tc</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> *</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">workflow</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">TaskContext</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">error</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Check if go.mod contains migration tools</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Run migration tests</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Verify schema compatibility</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Registered stages appear alongside built-in stages. A workflow in <code>config.toml</code> can reference them by name:</p><div class="language-toml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">toml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[[</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">workflows</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">stages</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">name = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;db-migration&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # matches the .go file</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">source = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;repo&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # loaded from .archie/stages/</span></span></code></pre></div><h3 id="skill-scripts-archie-skills-skill-scripts" tabindex="-1">Skill scripts (<code>.archie/skills/&lt;skill&gt;/scripts/</code>) <a class="header-anchor" href="#skill-scripts-archie-skills-skill-scripts" aria-label="Permalink to &quot;Skill scripts (`.archie/skills/&lt;skill&gt;/scripts/`)&quot;">​</a></h3><p>Skills can ship Go scripts that archie-core interprets:</p><div class="language-go vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">go</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// .archie/skills/security-audit/scripts/gitleaks.go</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">package</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> main</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">fmt</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">os/exec</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">context</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">func</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> main</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> context.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Background</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">()</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> cmd </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> exec.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">CommandContext</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(ctx, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;gitleaks&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;detect&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;--no-git&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;--verbose&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> out, _ </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> cmd.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">CombinedOutput</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">()</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> fmt.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Println</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(out))</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Skills reference these scripts naturally in their instructions: &quot;Run <code>scripts/gitleaks.go</code> to scan for secrets.&quot;</p><hr><h2 id="api-surface-archie-core-exposes-to-yaegi" tabindex="-1">API surface archie-core exposes to Yaegi <a class="header-anchor" href="#api-surface-archie-core-exposes-to-yaegi" aria-label="Permalink to &quot;API surface archie-core exposes to Yaegi&quot;">​</a></h2><p>Via <code>i.Use()</code>, the daemon pre-loads symbols that interpreted code can import:</p><table tabindex="0"><thead><tr><th>Package</th><th>What&#39;s exposed</th></tr></thead><tbody><tr><td><code>archie-core/internal/workflow</code></td><td><code>Stage</code>, <code>TaskContext</code>, <code>Outcome</code></td></tr><tr><td><code>archie-core/internal/gate</code></td><td><code>GateContext</code>, <code>Finding</code>, <code>Block</code></td></tr><tr><td><code>stdlib</code></td><td>Full Go standard library (stdlib.Symbols)</td></tr></tbody></table><p>Generated with <code>yaegi extract</code> -- same approach Traefik and Vikunja use. A <code>//go:generate yaegi extract ...</code> line in the source triggers symbol table generation during <code>go generate</code>.</p><hr><h2 id="limitations" tabindex="-1">Limitations <a class="header-anchor" href="#limitations" aria-label="Permalink to &quot;Limitations&quot;">​</a></h2><p>From Yaegi&#39;s own docs:</p><ul><li><strong>No assembly files</strong> (<code>.s</code> not supported)</li><li><strong>No CGo</strong> (can&#39;t call C code -- the daemon is pure Go, so this doesn&#39;t matter)</li><li><strong>No compiler/linker directives</strong> (no <code>//go:embed</code>, etc. -- fine for gate scripts)</li><li><strong>Interfaces from pre-compiled code can&#39;t be added dynamically</strong> -- the daemon must pre-compile wrapper types for any interface interpreted code needs to implement</li><li><strong>Slower than compiled code</strong> -- gate scripts run once per commit, not in hot paths; negligible impact</li></ul><p>The Vikunja PR documents a specific Yaegi quirk: <strong>typed factory functions required.</strong> You can&#39;t do <code>v.Interface().(MyInterface)</code> on a value returned from interpreted code. Each interface needs its own factory:</p><div class="language-go vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">go</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">func</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> NewGate</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Gate</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">return</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &amp;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">MyGate</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{} }</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">func</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> NewReportable</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Reportable</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">return</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &amp;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">MyGate</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{} }</span></span></code></pre></div><hr><h2 id="implementation-phases" tabindex="-1">Implementation phases <a class="header-anchor" href="#implementation-phases" aria-label="Permalink to &quot;Implementation phases&quot;">​</a></h2><h3 id="phase-1-gate-functions-implemented" tabindex="-1">Phase 1: Gate functions -- implemented <a class="header-anchor" href="#phase-1-gate-functions-implemented" aria-label="Permalink to &quot;Phase 1: Gate functions -- implemented&quot;">​</a></h3><ul><li><code>yaegi</code> added as a dependency</li><li>Symbol table for <code>GateContext</code>, <code>Finding</code> generated via <code>yaegi extract</code> into <code>internal/gate/gateextract</code> (a separate package from <code>internal/gate</code> itself, avoiding the self-import cycle extracting a package&#39;s own symbols creates)</li><li><code>internal/gate/gateeval.Evaluate</code>: loads <code>.archie/gate.go</code> from the worktree, interprets it, calls <code>Check()</code>; panics are recovered</li><li>Wired in as <code>workflow.StageYaegiGate</code>, run after the final commit in both the <code>implement</code> and <code>tdd</code> workflows</li><li>Error findings park the task; warn findings are logged only</li></ul><h3 id="phase-2-custom-stages-implemented" tabindex="-1">Phase 2: Custom stages -- implemented <a class="header-anchor" href="#phase-2-custom-stages-implemented" aria-label="Permalink to &quot;Phase 2: Custom stages -- implemented&quot;">​</a></h3><ul><li>Symbol table for <code>workflow.Stage</code>/<code>TaskContext</code>/<code>Outcome</code> generated into <code>internal/workflow/wfextract</code></li><li><code>internal/workflow/wfeval.Discover</code> scans <code>.archie/stages/*.go</code> in filename order and calls each file&#39;s exported <code>Stage()</code> function</li><li><code>TaskContext.CustomStages</code> is an injected <code>func(dir string) ([]Stage, error)</code> -- the composition root (<code>cmd/archied</code>) wires it to <code>wfeval.Discover</code>, keeping <code>internal/workflow</code> decoupled from its own generated symbol table</li><li><code>workflow.StageRepoStages</code> runs discovered stages in order right after the worktree is prepared, in both <code>implement</code> and <code>tdd</code></li><li>Simplification vs. the original sketch: stages are auto-discovered and always run (like <code>.archie/gate.go</code>) rather than referenced by name from <code>config.toml</code> -- the workflow engine has no data-driven stage graph today, so wiring arbitrary named stages into arbitrary positions would need a larger config-driven rework. Auto-run-in-order covers the PRD&#39;s actual use case (a repo-defined pre-flight/setup hook) without it.</li></ul><h3 id="phase-3-skill-scripts-implemented" tabindex="-1">Phase 3: Skill scripts -- implemented <a class="header-anchor" href="#phase-3-skill-scripts-implemented" aria-label="Permalink to &quot;Phase 3: Skill scripts -- implemented&quot;">​</a></h3><ul><li><code>internal/skillscript.Run</code> interprets a <code>.go</code> file via <code>i.EvalPath</code>, which (like <code>go run</code>) evaluates and calls its <code>main()</code>; stdout/stderr are captured via <code>interp.Options</code></li><li>Uses <code>stdlib.Symbols</code> + <code>stdlib/unrestricted.Symbols</code> (not just <code>stdlib</code>) -- <code>os/exec</code> lives in the unrestricted set, and the PRD&#39;s own example script shells out via <code>os/exec</code></li><li>No archie-core-specific symbol table needed here -- skill scripts only touch the Go standard library</li><li>Exposed to the agent loop as a new <code>run_go_script</code> tool (<code>internal/agentexec/inprocess.go</code>), available in every agent stage; path is validated to stay inside the workspace</li><li>This is how &quot;the skill&#39;s instructions reference a script&quot; cashes out concretely: the agent calls <code>run_go_script</code> with the path instead of needing a Go toolchain in the sandbox</li></ul><h3 id="phase-4-hot-reload-not-needed-by-construction" tabindex="-1">Phase 4: Hot reload -- not needed, by construction <a class="header-anchor" href="#phase-4-hot-reload-not-needed-by-construction" aria-label="Permalink to &quot;Phase 4: Hot reload -- not needed, by construction&quot;">​</a></h3><ul><li>All three loaders (<code>gate.Evaluate</Line truncated
<script>window.__VP_HASH_MAP__=JSON.parse("{\"architecture_agent-system.md\":\"Coj6mPZw\",\"architecture_configuration.md\":\"BsVGi7ja\",\"architecture_dependencies-and-contracts.md\":\"ByRODJZC\",\"architecture_generated-documentation.md\":\"qELen1k6\",\"architecture_identity.md\":\"CB0DkYo9\",\"architecture_index.md\":\"DJpk2YHf\",\"architecture_messaging-and-work-intake.md\":\"Q7MxXQDB\",\"architecture_migration-decisions.md\":\"oN2eGfag\",\"architecture_organisation.md\":\"mAPb3vCC\",\"architecture_package-review.md\":\"7BZCENBd\",\"architecture_plugins-and-extensions.md\":\"DmzsC2M0\",\"architecture_policy.md\":\"4L33IZiY\",\"architecture_safe-change-and-recovery.md\":\"CdYeF0XF\",\"archive_archie-core-architecture.md\":\"Bqg5-owD\",\"archive_archie-core-skills-prd-v2.md\":\"D3RVdXag\",\"archive_archie-core-skills-prd.md\":\"D1oUBHEN\",\"archive_decisions.md\":\"DkenJ6mD\",\"archive_design.md\":\"BwF1bH5l\",\"archive_prds_multi-agent-collaboration.md\":\"zqWXF3O0\",\"archive_prds_typescript-plugin-engine.md\":\"DBR1GKuy\",\"archive_prds_yaegi-plugin-system.md\":\"V36uzfZI\",\"index.md\":\"BdS51Ijr\",\"prds_01-project-management.md\":\"DEpuIAgg\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Archie\",\"description\":\"Documentation for the Archie personal agent platform.\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/favicon.svg\",\"nav\":[{\"text\":\"Architecture\",\"link\":\"/architecture/\"}],\"sidebar\":{\"/architecture/\":[{\"text\":\"Architecture\",\"items\":[{\"text\":\"Overview\",\"link\":\"/architecture/\"},{\"text\":\"Repository Organisation\",\"link\":\"/architecture/organisation\"},{\"text\":\"Dependencies and Contracts\",\"link\":\"/architecture/dependencies-and-contracts\"},{\"text\":\"Agent System\",\"link\":\"/architecture/agent-system\"},{\"text\":\"Configuration\",\"link\":\"/architecture/configuration\"},{\"text\":\"Identity\",\"link\":\"/architecture/identity\"},{\"text\":\"Messaging and Work Intake\",\"link\":\"/architecture/messaging-and-work-intake\"},{\"text\":\"Plugins and Extensions\",\"link\":\"/architecture/plugins-and-extensions\"},{\"text\":\"Policy System\",\"link\":\"/architecture/policy\"},{\"text\":\"Safe Change and Recovery\",\"link\":\"/architecture/safe-change-and-recovery\"},{\"text\":\"Generated Documentation\",\"link\":\"/architecture/generated-documentation\"},{\"text\":\"Domain and Feature Review Procedure\",\"link\":\"/architecture/package-review\"},{\"text\":\"Migration Decisions\",\"link\":\"/architecture/migration-decisions\"}]}]},\"search\":{\"provider\":\"local\"},\"footer\":{\"message\":\"Built with VitePress.\",\"copyright\":\"Archie\"}},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":true}");</script>
</body>
</html>
-1
View File
@@ -1 +0,0 @@
import{t as p}from"./chunks/theme.B97NJxv0.js";import{R as s,a3 as i,a4 as u,a5 as c,a6 as l,a7 as f,a8 as d,a9 as m,aa as h,ab as g,ac as A,d as v,u as y,v as C,s as P,ad as b,ae as w,af as R,ag as E}from"./chunks/framework.BWuWLRhz.js";function r(e){if(e.extends){const a=r(e.extends);return{...a,...e,async enhanceApp(t){a.enhanceApp&&await a.enhanceApp(t),e.enhanceApp&&await e.enhanceApp(t)}}}return e}const n=r(p),S=v({name:"VitePressApp",setup(){const{site:e,lang:a,dir:t}=y();return C(()=>{P(()=>{document.documentElement.lang=a.value,document.documentElement.dir=t.value})}),e.value.router.prefetchLinks&&b(),w(),R(),n.setup&&n.setup(),()=>E(n.Layout)}});async function T(){globalThis.__VITEPRESS__=!0;const e=_(),a=D();a.provide(u,e);const t=c(e.route);return a.provide(l,t),a.component("Content",f),a.component("ClientOnly",d),Object.defineProperties(a.config.globalProperties,{$frontmatter:{get(){return t.frontmatter.value}},$params:{get(){return t.page.value.params}}}),n.enhanceApp&&await n.enhanceApp({app:a,router:e,siteData:m}),{app:a,router:e,data:t}}function D(){return A(S)}function _(){let e=s;return h(a=>{let t=g(a),o=null;return t&&(e&&(t=t.replace(/\.js$/,".lean.js")),o=import(t)),s&&(e=!1),o},n.NotFound)}s&&T().then(({app:e,router:a,data:t})=>{a.go().then(()=>{i(a.route,t.site),e.mount("#app")})});export{T as createApp};
@@ -1,10 +0,0 @@
import{_ as t,o,c as n,a2 as r}from"./chunks/framework.BWuWLRhz.js";const h=JSON.parse('{"title":"Agent System","description":"","frontmatter":{},"headers":[],"relativePath":"architecture/agent-system.md","filePath":"architecture/agent-system.md","lastUpdated":null}'),a={name:"architecture/agent-system.md"};function i(s,e,d,c,l,u){return o(),n("div",null,[...e[0]||(e[0]=[r(`<h1 id="agent-system" tabindex="-1">Agent System <a class="header-anchor" href="#agent-system" aria-label="Permalink to &quot;Agent System&quot;">​</a></h1><p><strong>Status:</strong> Current-state investigation in progress<br><strong>Date:</strong> 2026-07-28<br><strong>Beads issue:</strong> <code>archie-core-5d7</code></p><h2 id="domain-framing" tabindex="-1">Domain framing <a class="header-anchor" href="#domain-framing" aria-label="Permalink to &quot;Domain framing&quot;">​</a></h2><p>The domain is the Agent System.</p><p><code>Task</code> is not a core Agent System concept. Forge tasks, forge issues, Jira issues, email, Telegram messages, webhooks, and future external inputs are channel-specific messages. Channels translate those messages into requests to the Agent System; external issue or task models MUST NOT shape execution state.</p><p>The current <code>store.Task</code> is a persisted workflow execution. Treating that row as a task-domain aggregate would incorrectly turn Archie into an agentic issue board.</p><h2 id="canonical-agent-interaction-model" tabindex="-1">Canonical agent interaction model <a class="header-anchor" href="#canonical-agent-interaction-model" aria-label="Permalink to &quot;Canonical agent interaction model&quot;">​</a></h2><p>An <strong>Agent</strong> is a persistent assistant selected for an interaction. It is not a model invocation and is not a WorkflowExecution.</p><p>Each Agent has its own:</p><ul><li>immutable acting <code>IdentityID</code> for ownership and audit;</li><li>durable memory and learned information about the user;</li><li>perspective, specialisation, instructions, and communication behaviour;</li><li>conversation history and channel bindings;</li><li>available tools, capabilities, and policy;</li><li>continuity across model or provider changes.</li></ul><p>The underlying model is a replaceable runtime dependency. Changing a model, provider, or model version MUST NOT create a new Agent, discard its memory, or change ownership of its history.</p><p>A user MAY create multiple Agents. Each Agent develops its own memory and view of the user from the interactions and responsibilities assigned to it. Memories MUST NOT be silently pooled merely because Agents belong to the same user or application.</p><p>Agent and Identity are separate aggregates. Every Agent references exactly one acting IdentityID, and no two Agents share an agent identity. User, system, and service-account identities may exist without an Agent.</p><p>An action initiated through an Agent records the Agent&#39;s acting IdentityID and, when applicable, the initiating user&#39;s IdentityID. A future fully automated WorkflowExecution MAY use an explicitly selected service-account identity for a concrete unattended use case; this is not the default execution identity.</p><h2 id="workflow-execution-identity" tabindex="-1">Workflow execution identity <a class="header-anchor" href="#workflow-execution-identity" aria-label="Permalink to &quot;Workflow execution identity&quot;">​</a></h2><p>A Workflow is owned by an IdentityID. By default, every WorkflowExecution acts as the Workflow owner&#39;s identity.</p><p>Future delegated execution MAY add an explicit <code>RunAsIdentityID</code> assignment to a Workflow. This allows a Workflow owner to select another user or service-account identity for execution without changing Workflow ownership. Until that capability is deliberately introduced, owner identity and execution identity are the same.</p><p>WorkflowExecution audit records MUST preserve the Workflow owner, effective execution identity, initiating user when one exists, and any explicit delegation that selected a different run-as identity.</p><h2 id="memory-scopes" tabindex="-1">Memory scopes <a class="header-anchor" href="#memory-scopes" aria-label="Permalink to &quot;Memory scopes&quot;">​</a></h2><p>The Agent System requires four distinct durable memory scopes:</p><ul><li><strong>global shared memory</strong>: information intentionally available across the Archie application;</li><li><strong>agent-wide memory</strong>: general expertise, operating knowledge, and perspective owned by one Agent and safe for that Agent to use across users;</li><li><strong>user-wide memory</strong>: information associated with one user and available to authorized Agents serving that user;</li><li><strong>Agent-user relationship memory</strong>: private history and learned context from one particular Agent&#39;s relationship with one particular user.</li></ul><p>Agent-wide memory is private to its owning Agent by default. Another Agent MUST NOT Line truncated
<span class="line"><span>internal/domain/workflow</span></span></code></pre></div><p>The Agent domain owns persistent assistants, their specialisation, instructions, model-independent continuity, capability context, and associations with identity and memory.</p><p>The Workflow domain owns reusable, user- or Agent-defined behaviour and every durable execution of that behaviour. An Agent may invoke or define a Workflow, but the Workflow is not part of the Agent aggregate and does not require a conversational Agent interaction to execute.</p><h2 id="canonical-workflow-model" tabindex="-1">Canonical workflow model <a class="header-anchor" href="#canonical-workflow-model" aria-label="Permalink to &quot;Canonical workflow model&quot;">​</a></h2><p>The Workflow feature uses these canonical terms:</p><ul><li><strong>Workflow</strong>: a reusable, versioned definition of how an agent behaves and performs a kind of work.</li><li><strong>WorkflowExecution</strong>: one durable execution of a specific Workflow version.</li><li><strong>WorkflowStep</strong>: one defined operation in a Workflow.</li><li><strong>StepExecution</strong>: the recorded execution and outcome of one WorkflowStep.</li><li><strong>Attempt</strong>: a retry of the same WorkflowExecution, not a new execution.</li></ul><p>A Workflow MAY structure any repeatable agent behaviour, including personal assistance and scheduled routines. For example, a morning email review may combine a schedule event, message retrieval tool, LLM classification and summarisation, and delivery of the resulting rundown. Workflow is therefore not restricted to forge work, source changes, or requests submitted by a user at execution time.</p><p>Workflows are extensible through Workflow-owned plugins. The Workflow domain defines the typed plugin registration, definition, validation, versioning, and execution contracts. Users and Agents may define reusable Workflows through those contracts.</p><p>The generic plugin contract remains metadata-only. It MUST NOT own Workflow semantics or replace the Workflow registry with generic hooks.</p><p><code>Workflow</code> and <code>WorkflowExecution</code> are the names used in architecture, generated reference, configuration, commands, events, and external contracts. The implementation MAY use package qualification to remain concise:</p><div class="language-go vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">go</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">workflow.Definition</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">workflow.Execution</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">workflow.Step</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">workflow.StepExecution</span></span></code></pre></div><p>The unqualified name <code>Execution</code> MUST NOT be used in cross-domain contracts or documentation because it is ambiguous among workflow, tool, command, policy, and service execution.</p><h2 id="current-workflow-execution-feature" tabindex="-1">Current workflow-execution feature <a class="header-anchor" href="#current-workflow-execution-feature" aria-label="Permalink to &quot;Current workflow-execution feature&quot;">​</a></h2><p>The current feature takes a channel request through agent execution and a durable outcome.</p><p>Current execution state includes source-message references, owning identity, repository, selected workflow and stage, agent output, branch and pull-request references, token and iteration counts, retry information, human-wait information, and failure details.</p><p>The current <code>store.Task</code> lifecycle uses:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>queued -&gt; running</span></span>
<span class="line"><span>running -&gt; waiting_human | pr_open | merged | parked | closed_wont_do</span></span>
<span class="line"><span>waiting_human -&gt; queued | closed_wont_do</span></span>
<span class="line"><span>parked -&gt; queued | dead</span></span>
<span class="line"><span>pr_open -&gt; merged | rejected</span></span>
<span class="line"><span>running after crash -&gt; queued</span></span></code></pre></div><p>Workflows select and sequence deterministic and agent-run stages. Implement, TDD, feasibility, and bootstrap are current Workflow definitions. WorkflowExecutions may run in-process or be handed wholesale to <code>archie-agent</code>.</p><h2 id="current-workflow-feature-placement" tabindex="-1">Current workflow-feature placement <a class="header-anchor" href="#current-workflow-feature-placement" aria-label="Permalink to &quot;Current workflow-feature placement&quot;">​</a></h2><p>The behaviour is divided across technical packages:</p><ul><li><code>internal/store</code> defines the current <code>Task</code> execution record and status strings and persists mutable state and transition history.</li><li><code>internal/daemon</code> discovers, claims, schedules, retries, recovers, processes, waits for human input, and reconciles pull requests.</li><li><code>internal/workflow</code> routes work, executes stages, mutates tasks, applies outcomes, parks failures, and performs forge/worktree operations.</li><li><code>internal/agentexec</code> defines and runs individual autonomous-stage protocols.</li><li><code>internal/taskrun</code> hands a complete WorkflowExecution to a container worker.</li><li><code>internal/gate</code> and repository configuration define execution constraints.</li><li><code>internal/gateway</code> duplicates task status strings and applies task-control rules.</li><li>forge, worktree, NATS, SQLite, containers, and agent runtimes are concrete dependencies mixed into orchestration.</li></ul><h2 id="current-task-meanings-and-required-replacements" tabindex="-1">Current <code>task</code> meanings and required replacements <a class="header-anchor" href="#current-task-meanings-and-required-replacements" aria-label="Permalink to &quot;Current \`task\` meanings and required replacements&quot;">​</a></h2><p>The existing code uses <code>task</code> for unrelated concepts. Migration MUST resolve each meaning deliberately; a global text replacement is prohibited.</p><table tabindex="0"><thead><tr><th>Current meaning</th><th>Representative locations</th><th>Target concept</th><th>Requirements</th></tr></thead><tbody><tr><td>Forge issue or external task</td><td><code>internal/forge</code>, daemon polling</td><td>Channel message</td><td>Preserve the channel&#39;s native reference and payload. Translate it into an Agent System request without importing forge or issue semantics into Workflow.</td></tr><tr><td>Jira issue or other external work item</td><td>Messaging infrastructure adapter</td><td>Channel message or external artifact</td><td>The external system retains its own vocabulary inside its integration. Its record may lead to an accepted work request but is not a Workflow or WorkflowExecution.</td></tr><tr><td>Persisted <code>store.Task</code> row/document</td><td><code>internal/store</code>, <code>internal/nell</code></td><td>WorkflowExecution</td><td>Own identity, Workflow ID and version, lifecycle, source-message reference, outputs, attempts, and outcome. Persistence implements the Agent System repository contract.</td></tr><tr><td>Task status and transition history</td><td><code>store.Status*</code>, <code>transitions</code>, Nell documents</td><td>WorkflowExecution lifecycle and domain events</td><td>Enforce legal transitions atomically. Domain events and state changes cannot diverge. Remove duplicated status strings from consumers.</td></tr><tr><td>Claimed or queued task</td><td><code>ClaimNext</code>, <code>ClaimByIssue</code>, <code>RecoverStale</code></td><td>Scheduled WorkflowExecution</td><td>Claim by WorkflowExecution ID and expected version/state. Crash recovery and leases must not silently create a new execution.</td></tr><tr><td><code>workflow.TaskContext</code></td><td><code>internal/workflow</code></td><td>WorkflowExecution context</td><td>Replace the mutable service bag with execution state plus narrow step-required contracts. Complete application configuration and unrelated services are forbidden.</td></tr><tr><td><code>taskrun.Request</code> and <code>taskrun.Response</code></td><td><code>internal/taskrun</code>, <code>cmd/archie-agent</code></td><td>WorkflowExecution handoff</td><td>This is the versioned worker contract for executing a WorkflowExecution. It carries domain-owned execution data, not store rows or global configuration DTOs.</td></tr><tr><td>Per-stage <code>agentexec.Request.TaskID</code></td><td><code>internal/agentexec</code></td><td>WorkflowExecutionID correlation</td><td>An agent invocation is a bounded WorkflowStep execution. Correlate request/result with WorkflowExecutionID, StepExecutionID, attempt, and protocol version.</td></tr><tr><td>NATS <code>TaskMessage</code> and <code>archie.task.*</code></td><td><code>internal/nats</code></td><td>Channel request or WorkflowExecution transport</td><td>Discovery messages and execution dispatch are different contracts and subjectLine truncated
@@ -1 +0,0 @@
import{_ as t,o,c as n,a2 as r}from"./chunks/framework.BWuWLRhz.js";const h=JSON.parse('{"title":"Agent System","description":"","frontmatter":{},"headers":[],"relativePath":"architecture/agent-system.md","filePath":"architecture/agent-system.md","lastUpdated":null}'),a={name:"architecture/agent-system.md"};function i(s,e,d,c,l,u){return o(),n("div",null,[...e[0]||(e[0]=[r("",67)])])}const m=t(a,[["render",i]]);export{h as __pageData,m as default};
@@ -1 +0,0 @@
import{_ as t,o,c as i,a2 as a}from"./chunks/framework.BWuWLRhz.js";const h=JSON.parse('{"title":"Configuration","description":"","frontmatter":{},"headers":[],"relativePath":"architecture/configuration.md","filePath":"architecture/configuration.md","lastUpdated":null}'),n={name:"architecture/configuration.md"};function d(r,e,c,s,l,u){return o(),i("div",null,[...e[0]||(e[0]=[a('<h1 id="configuration" tabindex="-1">Configuration <a class="header-anchor" href="#configuration" aria-label="Permalink to &quot;Configuration&quot;">​</a></h1><p><strong>Status:</strong> Approved; existing-type assignment is ongoing<br><strong>Date:</strong> 2026-07-28<br><strong>Beads issue:</strong> <code>archie-core-5d7</code></p><h2 id="ownership" tabindex="-1">Ownership <a class="header-anchor" href="#ownership" aria-label="Permalink to &quot;Ownership&quot;">​</a></h2><p>Configuration has two separate responsibilities:</p><ol><li><code>internal/infrastructure/configuration</code> loads files, environment variables, secret references, overlays, and compatibility representations.</li><li>Each domain and plugin owns the typed runtime settings required for its behaviour.</li></ol><p><code>internal/app</code> translates external input into those settings, validates cross-capability combinations, and supplies each component only its own settings.</p><p>The following are prohibited:</p><ul><li>passing complete application configuration into a domain;</li><li>making a domain depend on TOML, YAML, environment-variable names, secret references, or a configuration library;</li><li>defining a central runtime configuration type imported across the system;</li><li>placing plugin options in an unrelated global configuration model.</li></ul><h2 id="private-input-document" tabindex="-1">Private input document <a class="header-anchor" href="#private-input-document" aria-label="Permalink to &quot;Private input document&quot;">​</a></h2><p><code>internal/infrastructure/configuration</code> MAY use a complete decoded document while discovering files, decoding sections, and applying overlays. It is an input-boundary DTO only.</p><p>The document:</p><ul><li>remains private to the configuration infrastructure;</li><li>is composed from separately defined feature sections;</li><li>is immediately translated by application composition;</li><li>is never returned as the application&#39;s runtime model;</li><li>is never passed through runtime components.</li></ul><p>External DTOs and domain runtime settings are separate types.</p><p>Plugins supply external configuration definitions through a narrow extension contract. The core loader MUST NOT gain a field or recognized filename for every plugin.</p><p>Invalid configuration input MUST NOT replace active valid settings or terminate unaffected capabilities. Configuration changes use the candidate validation, promotion, audit, and recovery requirements in <a href="./safe-change-and-recovery">safe-change-and-recovery.md</a>.</p><h2 id="dissolution-of-internal-config" tabindex="-1">Dissolution of <code>internal/config</code> <a class="header-anchor" href="#dissolution-of-internal-config" aria-label="Permalink to &quot;Dissolution of `internal/config`&quot;">​</a></h2><p><code>internal/config</code> has no target location. It MUST be dissolved and MUST NOT survive as a shared package, configuration domain, or renamed global model.</p><p>Its loading behaviour moves to <code>internal/infrastructure/configuration</code>. Existing types and methods are reassigned by behaviour. Repository execution policy, dispatch policy, retry policy, ecosystem defaults, tool policy, memory settings, indexing settings, provider settings, and channel settings move to their respective owners.</p><h2 id="repository-settings" tabindex="-1">Repository settings <a class="header-anchor" href="#repository-settings" aria-label="Permalink to &quot;Repository settings&quot;">​</a></h2><p>The existing <code>config.Repo</code> MUST NOT move intact into a repository domain or shared settings package. A managed repository is an application association:</p><ul><li>work intake owns which repository references an identity monitors;</li><li>task execution owns gates, preflight, test protection, ecosystem behaviour, and change limits;</li><li>task lifecycle owns retry behaviour;</li><li>scheduling owns concurrency policy;</li><li>workspace management owns base branch and persistent-storage requirements.</li></ul><p>Application composition correlates these settings by repository reference. No domain receives a universal repository profile.</p><h2 id="documentation" tabindex="-1">Documentation <a class="header-anchor" href="#documentation" aria-label="Permalink to &quot;Documentation&quot;">​</a></h2><p>Generated configuration reference describes external sections and their owning capabilities. It MUST NOT establish a global Go configuration structure as the public contract.</p><h2 id="value-classification-rule" tabindex="-1">Value classificaLine truncated
@@ -1 +0,0 @@
import{_ as t,o,c as i,a2 as a}from"./chunks/framework.BWuWLRhz.js";const h=JSON.parse('{"title":"Configuration","description":"","frontmatter":{},"headers":[],"relativePath":"architecture/configuration.md","filePath":"architecture/configuration.md","lastUpdated":null}'),n={name:"architecture/configuration.md"};function d(r,e,c,s,l,u){return o(),i("div",null,[...e[0]||(e[0]=[a("",57)])])}const m=t(n,[["render",d]]);export{h as __pageData,m as default};
@@ -1,4 +0,0 @@
import{_ as n,o as a,c as t,a2 as i}from"./chunks/framework.BWuWLRhz.js";const m=JSON.parse('{"title":"Dependencies and Contracts","description":"","frontmatter":{},"headers":[],"relativePath":"architecture/dependencies-and-contracts.md","filePath":"architecture/dependencies-and-contracts.md","lastUpdated":null}'),s={name:"architecture/dependencies-and-contracts.md"};function r(o,e,c,d,l,p){return a(),t("div",null,[...e[0]||(e[0]=[i(`<h1 id="dependencies-and-contracts" tabindex="-1">Dependencies and Contracts <a class="header-anchor" href="#dependencies-and-contracts" aria-label="Permalink to &quot;Dependencies and Contracts&quot;">​</a></h1><p><strong>Status:</strong> Approved foundation<br><strong>Date:</strong> 2026-07-28<br><strong>Beads issue:</strong> <code>archie-core-5d7</code></p><h2 id="dependency-direction" tabindex="-1">Dependency direction <a class="header-anchor" href="#dependency-direction" aria-label="Permalink to &quot;Dependency direction&quot;">​</a></h2><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>domain and shared application contracts &lt;- infrastructure implementations</span></span>
<span class="line"><span> ^</span></span>
<span class="line"><span> |</span></span>
<span class="line"><span> application composition</span></span></code></pre></div><p>The following rules are strict:</p><ol><li>Domains MUST NOT import <code>internal/infrastructure</code>.</li><li>A domain defines the smallest interfaces required to perform its work.</li><li>Infrastructure implements those interfaces and translates external representations at the boundary.</li><li>Only application composition chooses concrete implementations.</li><li>A domain MUST NOT manipulate another domain&#39;s state or call its internal services.</li><li>Cross-domain work uses an explicitly designed command, event, or approved shared contract.</li><li>Implementation difficulty is not permission to violate a boundary.</li></ol><p>Broker messages, database rows, SDK response types, and configuration DTOs MUST NOT leak into domain models.</p><h2 id="commands-and-events" tabindex="-1">Commands and events <a class="header-anchor" href="#commands-and-events" aria-label="Permalink to &quot;Commands and events&quot;">​</a></h2><ul><li>An event records something that happened and is owned by its publishing domain.</li><li>A command requests an action and is owned by the domain expected to handle it.</li><li>Consumers do not redefine an event&#39;s meaning.</li><li>Senders obey the receiving domain&#39;s command contract.</li><li>There is no generic package containing unrelated application messages.</li></ul><h2 id="event-bus" tabindex="-1">Event bus <a class="header-anchor" href="#event-bus" aria-label="Permalink to &quot;Event bus&quot;">​</a></h2><p><code>internal/eventbus</code> is an approved shared application contract. It defines only the messaging behaviour Archie requires, including publication, subscription, delivery outcomes, and required lifecycle semantics.</p><p>It MUST remain broker-neutral. NATS subjects, JetStream configuration, consumer groups, acknowledgements, reconnection, and serialization belong under <code>internal/infrastructure/eventbus/nats</code> unless Archie explicitly requires a semantic guarantee in the shared contract.</p><p>Message schemas stay with their owning domains. The event bus transports messages; it does not own their meaning.</p><h2 id="wire-contracts-and-generation" tabindex="-1">Wire contracts and generation <a class="header-anchor" href="#wire-contracts-and-generation" aria-label="Permalink to &quot;Wire contracts and generation&quot;">​</a></h2><p>Canonical worker and service wire contracts and their authoritative generation inputs are owned by the domain or capability that defines their meaning. They MUST NOT be centralized in <code>internal/infrastructure/spec</code> or another generic schema package.</p><p>Infrastructure owns:</p><ul><li>generic contract-generation machinery;</li><li>transport-specific adapters and generated implementations;</li><li>RPC, REST, NATS, and other external encoding and delivery concerns.</li></ul><p>For example, agent-worker requests and results belong to task execution. Subprocess, NATS, or HTTP representations are infrastructure implementations of that contract. The same rule applies independently to forge, persistence, workspace, and other service contracts.</p>`,18)])])}const h=n(s,[["render",r]]);export{m as __pageData,h as default};
@@ -1 +0,0 @@
import{_ as n,o as a,c as t,a2 as i}from"./chunks/framework.BWuWLRhz.js";const m=JSON.parse('{"title":"Dependencies and Contracts","description":"","frontmatter":{},"headers":[],"relativePath":"architecture/dependencies-and-contracts.md","filePath":"architecture/dependencies-and-contracts.md","lastUpdated":null}'),s={name:"architecture/dependencies-and-contracts.md"};function r(o,e,c,d,l,p){return a(),t("div",null,[...e[0]||(e[0]=[i("",18)])])}const h=n(s,[["render",r]]);export{m as __pageData,h as default};
@@ -1,59 +0,0 @@
import{_ as a,o as i,c as s,a2 as t}from"./chunks/framework.BWuWLRhz.js";const u=JSON.parse('{"title":"Generated Documentation and Documentation Site","description":"","frontmatter":{},"headers":[],"relativePath":"architecture/generated-documentation.md","filePath":"architecture/generated-documentation.md","lastUpdated":null}'),n={name:"architecture/generated-documentation.md"};function l(o,e,r,d,p,c){return i(),s("div",null,[...e[0]||(e[0]=[t(`<h1 id="generated-documentation-and-documentation-site" tabindex="-1">Generated Documentation and Documentation Site <a class="header-anchor" href="#generated-documentation-and-documentation-site" aria-label="Permalink to &quot;Generated Documentation and Documentation Site&quot;">​</a></h1><p><strong>Status:</strong> Initial generator and site scaffold in progress<br><strong>Date:</strong> 2026-07-28<br><strong>Beads issue:</strong> <code>archie-core-5d7</code></p><h2 id="purpose" tabindex="-1">Purpose <a class="header-anchor" href="#purpose" aria-label="Permalink to &quot;Purpose&quot;">​</a></h2><p>Archie&#39;s documentation-generation approach is:</p><ul><li>production Go code, registries, configuration, and CLI behaviour remain the source of truth for published contracts;</li><li>a repository-local Go generator extracts and normalizes documentation data;</li><li>the generator writes deterministic JSON/data files and protocol schemas;</li><li>VitePress data loaders, components, and templates render the generated data into reference pages;</li><li>GitHub Actions builds and publishes the static site.</li></ul><p>Hugo is not part of the target architecture.</p><p>The documentation system is rooted at:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>.github/workflows/docs.yml</span></span>
<span class="line"><span>tools/</span></span>
<span class="line"><span> go.mod</span></span>
<span class="line"><span> go.sum</span></span>
<span class="line"><span> docsgen/</span></span>
<span class="line"><span> main.go</span></span>
<span class="line"><span>docs/</span></span>
<span class="line"><span> .vitepress/</span></span>
<span class="line"><span> public/</span></span>
<span class="line"><span> package.json</span></span>
<span class="line"><span> pnpm-lock.yaml</span></span>
<span class="line"><span> pnpm-workspace.yaml</span></span>
<span class="line"><span> *.md</span></span></code></pre></div><h3 id="vitepress-site" tabindex="-1">VitePress site <a class="header-anchor" href="#vitepress-site" aria-label="Permalink to &quot;VitePress site&quot;">​</a></h3><p>The <code>docs</code> site provides:</p><ul><li>VitePress 1.6.x with pnpm;</li><li>Markdown content at the site root;</li><li>repository-owned navigation and sidebar configuration;</li><li>local full-text search;</li><li>clean URLs and last-updated metadata;</li><li>build output under <code>.vitepress/dist</code>;</li><li>GitHub Pages-compatible static output;</li></ul><h3 id="github-pages-workflow" tabindex="-1">GitHub Pages workflow <a class="header-anchor" href="#github-pages-workflow" aria-label="Permalink to &quot;GitHub Pages workflow&quot;">​</a></h3><p>The workflow provides:</p><ul><li>full-history checkout for VitePress <code>lastUpdated</code>;</li><li>pinned pnpm major version;</li><li>Node setup and pnpm caching;</li><li>VitePress cache reuse;</li><li>frozen-lockfile installation;</li><li>static build, artifact upload, and Pages deployment;</li><li>serialized deployments without cancelling an in-progress publish.</li></ul><h2 id="single-source-of-truth" tabindex="-1">Single source of truth <a class="header-anchor" href="#single-source-of-truth" aria-label="Permalink to &quot;Single source of truth&quot;">​</a></h2><p>Every published capability has one authoritative machine-readable definition owned by its domain or application boundary. Generated documentation derives from those definitions.</p><p>Generated reference includes:</p><ul><li>domain commands and events;</li><li>Messages and typed message content;</li><li>Agent and Workflow contracts;</li><li>WorkflowSteps and Workflow plugin capability contracts;</li><li>policies and their typed inputs and outcomes;</li><li>tools and capabilities;</li><li>CLI commands, arguments, flags, defaults, and help;</li><li>runtime settings, types, defaults, validation, and secret metadata;</li><li>public worker and transport contracts;</li><li>indexes of registered functionality;</li><li>deprecation information.</li></ul><p>Handwritten documents contain:</p><ul><li>architecture decisions and rationale;</li><li>tutorials and operational guides;</li><li>examples and walkthroughs;</li><li>migration guidance;</li><li>conceptual explanations.</li></ul><p>Handwritten documents link to generated reference rather than copying authoritative tables.</p><h2 id="target-generation-architecture" tabindex="-1">Target generation architecture <a class="header-anchor" href="#target-generation-architecture" aria-label="Permalink to &quot;Target generation architecture&quot;">​</a></h2><p><code>tools/docsgen</code> is Archie&#39;s documentation extractor and normalizer. It produces structured documentation data and protocol specifications. It does not own page layout and MUST NOT generate Markdown pages or fragments.</p><p>The generator is divided internally into reusable stages:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>load registries and types</span></span>
<span class="line"><span> -&gt; normalize documentation model</span></span>
<span class="line"><span> -&gt; validate ownership and identifiers</span></span>
<span class="line"><span> -&gt; serialize data and protocol artifacts</span></span>
<span class="line"><span> -&gt; compare or write output</span></span></code></pre></div><p>The normalized documentation model prevents each output renderer from independently interpreting Go types. It contains stable documentation IDs, owners, names, descriptions, source references, versions, deprecations, fields, defaults, validation, secret classifications, and relationships.</p><p>Initial generator targets:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>docsgen data</span></span>
<span class="line"><span>docsgen asyncapi</span></span>
<span class="line"><span>docsgen all</span></span>
<span class="line"><span>docsgen check</span></span></code></pre></div><ul><li><code>data</code> writes the normalized JSON consumed by VitePress.</li><li><code>asyncapi</code> writes protocol schemas and envelopes.</li><li><code>all</code> generates every committed artifact.</li><li><code>check</code> generates into a temporary directory and fails on drift.</li></ul><p>The command may use subcommands or an equivalent explicit <code>--target</code> flag. It MUST retain one normalization and validation path.</p><h2 id="target-output" tabindex="-1">Target output <a class="header-anchor" href="#target-output" aria-label="Permalink to &quot;Target output&quot;">​</a></h2><p>During adaptation, <code>docs</code> remains the staging site. Generated outputs live in a visibly owned subtree:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>docs/</span></span>
<span class="line"><span> data/</span></span>
<span class="line"><span> generated/</span></span>
<span class="line"><span> catalog.json</span></span>
<span class="line"><span> contracts.json</span></span>
<span class="line"><span> cli.json</span></span>
<span class="line"><span> configuration.json</span></span>
<span class="line"><span> messaging.json</span></span>
<span class="line"><span> agents.json</span></span>
<span class="line"><span> workflows.json</span></span>
<span class="line"><span> policies.json</span></span>
<span class="line"><span> plugins.json</span></span>
<span class="line"><span> tools.json</span></span>
<span class="line"><span> public/</span></span>
<span class="line"><span> schemas/</span></span>
<span class="line"><span> asyncapi-header.yaml</span></span>
<span class="line"><span> archie.yaml</span></span>
<span class="line"><span> .vitepress/</span></span>
<span class="line"><span> config.mts</span></span>
<span class="line"><span> data/</span></span>
<span class="line"><span> reference.data.ts</span></span>
<span class="line"><span> theme/</span></span>
<span class="line"><span> components/</span></span>
<span class="line"><span> .tmp/</span></span></code></pre></div><p>All files under <code>data/generated/</code> and <code>public/schemas/</code> carry generated ownership metadata where their format permits it and MUST NOT be edited manually. <code>.tmp/</code> is generator-owned, ignored, and never committed.</p><p><code>catalog.json</code> is the deterministic machine-readable index used for:</p><ul><li>reference navigation and route inputs;</li><li>duplicate-ID and duplicate-route validation;</li><li>coverage checks;</li><li>source-to-data drift diagnostics;</li><li>future external consumers.</li></ul><p>VitePress loads these files at build time through a typed <code>.data.ts</code> loader. Pages and components import the loader&#39;s <code>data</code> export and render reference views. Archie uses a custom loader because the authoritative inputs are JSON; VitePress <code>createContentLoader</code> is reserved for Markdown content collections.</p><p>The final move from <code>docs/</code> to <code>docs/</code> occurs only after Archie content contains intentional Archie pages and the current architecture documents have an intentional destination. The staging name MUST NOT leak into public URLs.</p><h2 id="generation-steps" tabindex="-1">Generation steps <a class="header-anchor" href="#generation-steps" aria-label="Permalink to &quot;Generation steps&quot;">​</a></h2><h3 id="step-1-maintain-the-archie-tools-module" tabindex="-1">Step 1: maintain the Archie tools module <a class="header-anchor" href="#step-1-maintain-the-archie-tools-module" aria-label="Permalink to &quot;Step 1: maintain the Archie tools module&quot;">​</a></h3><p>Keep <code>tools/go.mod</code> isolated from the runtime module:</p><div class="language-go vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">go</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">module github.com</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">/</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">samcharles93</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">/</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">archie</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">core</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">/</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">tools</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">require github.com</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">/</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">samcharles93</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">/</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">archie</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">core v0.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">0.0</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">-</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">00010101000000</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">-</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">000000000000</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">replace github.com</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">/</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">samcharles93</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">/</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">archie</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">core </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ..</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">/</span></span></code></pre></div><p>Keep generator-only dependencies such as <code>invopop/jsonschema</code> and any future protocol-schema serializer in the nested tools module. They MUST NOT enter the root module.</p><p><code>docsgen</code> imports Archie-owned contracts and writes normalized Archie data and protocol artifacts.</p><h3 id="step-2-establish-authoritative-registries" tabindex="-1">Step 2: establish authoritative registries <a class="header-anchor" href="#step-2-establish-authoritative-registries" aria-label="Permalink to &quot;Step 2: establish authoritative registries&quot;">​</a></h3><p>The generator consumes domain-owned registries rather than scanning arbitrary packages for anything exported.</p><p>Each published definition supplies:</p><ul><li>stable documentation ID;</li><li>owning domain or boundary;</li><li>name and description;</li><li>version when versioned;</li><li>the Go type or declarative definition;</li><li>lifecycle and deprecation metadata;</li><li>source reference.</li></ul><p>Registries remain executable application definitions used by production code. A documentation-only duplicate registry is prohibited.</p><p>Where the migration has not yet created a final domain registry, the generator may use a narrow compatibility adapter over the current registry. That adapter has explicit deletion criteria.</p><p>The initial agent-execution and messaging schema set is such an adapter. It is deleted when those domains expose their production-owned documentation registries; adding another hardcoded type list to <code>docsgen</code> is prohibited.</p><h3 id="step-3-generate-asyncapi" tabindex="-1">Step 3: generate AsyncAPI <a class="header-anchor" href="#step-3-generate-asyncapi" aria-label="Permalink to &quot;Step 3: generate AsyncAPI&quot;">​</a></h3><p>Use Archie&#39;s messaging and worker wire registries as the authoritative inputs.</p><p>The static header continues to own:</p><ul><li>AsyncAPI version;</li><li>service and protocol description;</li><li>servers;</li><li>channels;</li><li>operations;</li><li>message envelope placement.</li></ul><p>The generator owns:</p><ul><li>component schemas;</li><li>discriminated concrete message lists;</li><li>generated envelopes;</li><li>rewritten schema references;</li><li>stable ordering.</li></ul><p>The generated protocol artifact becomes:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>docs/public/schemas/archie.yaml</span></span></code></pre></div><p>The final owner of each wire registry is the domain or capability defining its meaning. <code>docsgen</code> renders the contract; it does not own the message semantics.</p><h3 id="step-4-add-generated-documentation-data" tabindex="-1">Step 4: add generated documentation data <a class="header-anchor" href="#step-4-add-generated-documentation-data" aria-label="Permalink to &quot;Step 4: add generated documentation data&quot;">​</a></h3><p>Add extractors for the missing reference categories one vertical slice at a time.</p><p>Recommended implementation order:</p><ol><li>CLI commands and flags;</li><li>runtime configuration/settings;</li><li>Messaging commands, events, and message types;</li><li>Agent definitions and public commands;</li><li>Workflow definitions, WorkflowSteps, lifecycle, and plugin contracts;</li><li>policy definitions and typed outcomes;</li><li>tools and capability contracts;</li><li>worker and external wire contracts.</li></ol><p>Each category extractor contributes:</p><ul><li>stable IDs, owners, routes, and display ordering;</li><li>fields, types, defaults, and validation metadata;</li><li>source references;</li><li>version and deprecation information;</li><li>relationships to commands, events, policies, and contracts.</li></ul><p>The first vertical slice proves the normalized model and deterministic JSON serialization. Later categories reuse it rather than introducing category-specific ad hoc output formats.</p><h3 id="step-5-render-data-with-vitepress" tabindex="-1">Step 5: render data with VitePress <a class="header-anchor" href="#step-5-render-data-with-vitepress" aria-label="PeLine truncated
<span class="line"><span>task docs:check # go -C tools run ./docsgen check, then build VitePress</span></span>
<span class="line"><span>task docs:serve # generate, install if needed, then start VitePress dev</span></span>
<span class="line"><span>task docs:build # generate/check and create the production static site</span></span></code></pre></div><p>Commands use explicit paths:</p><div class="language-sh vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sh</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">go</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -C</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> tools</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./docsgen</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> all</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --repo-root</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ..</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">go</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -C</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> tools</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./docsgen</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> check</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --repo-root</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ..</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> docs</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> install</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --frozen-lockfile</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> docs</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> docs</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build</span></span></code></pre></div><p>The final command syntax must match the implemented CLI, but these task names and responsibilities are fixed.</p><p><code>task check</code> runs <code>docs:check</code>. Generated drift, invalid Markdown, dead links, or a failed VitePress build block completion.</p><h3 id="step-9-adapt-ci-and-pages-deployment" tabindex="-1">Step 9: adapt CI and Pages deployment <a class="header-anchor" href="#step-9-adapt-ci-and-pages-deployment" aria-label="Permalink to &quot;Step 9: adapt CI and Pages deployment&quot;">​</a></h3><p>The workflow watches:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>.github/workflows/docs.yml</span></span>
<span class="line"><span>docs/**</span></span>
<span class="line"><span>tools/go.mod</span></span>
<span class="line"><span>tools/go.sum</span></span>
<span class="line"><span>tools/docsgen/**</span></span>
<span class="line"><span>authoritative domain registry and type paths</span></span></code></pre></div><p>The build job:</p><ol><li>checks out full history;</li><li>installs the repository&#39;s Go version;</li><li>runs <code>docsgen check</code>;</li><li>installs the pinned pnpm version;</li><li>installs the configured Node version;</li><li>restores pnpm and VitePress caches;</li><li>installs dependencies with the frozen lockfile;</li><li>builds VitePress;</li><li>uploads <code>docs/.vitepress/dist</code>.</li></ol><p>The deploy job uses the required Pages permissions, environment, concurrency, and artifact deployment flow.</p><p>CI MUST check generated output; it MUST NOT regenerate and silently publish uncommitted differences.</p><h3 id="step-10-remove-non-source-artifacts-and-cut-over" tabindex="-1">Step 10: remove non-source artifacts and cut over <a class="header-anchor" href="#step-10-remove-non-source-artifacts-and-cut-over" aria-label="Permalink to &quot;Step 10: remove non-source artifacts and cut over&quot;">​</a></h3><p>Before treating the site as Archie documentation:</p><ul><li>keep <code>node_modules/</code> out of source control;</li><li>keep <code>.vitepress/dist/</code> out of source control;</li><li>ensure both paths are ignored;</li><li>remove Markdown, examples, specs, generated schemas, and assets that do not describe Archie;</li><li>adapt retained content and prove it against Archie code;</li><li>update <code>docs.go</code> and its tests to embed only intentional runtime documentation;</li><li>decide which current <code>docs/prds</code> remain published architecture pages and which remain repository-only planning documents;</li><li>rename <code>docs</code> to its final location;</li><li>update workflow, Taskfile, links, and embed paths atomically.</li></ul><p>Documents MUST describe Archie before they are published.</p><h2 id="hook-and-ci-policy" tabindex="-1">Hook and CI policy <a class="header-anchor" href="#hook-and-ci-policy" aria-label="Permalink to &quot;Hook and CI policy&quot;">​</a></h2><p>Generated documentation is committed.</p><p>The pre-commit hook:</p><ol><li>detects authoritative definition or generator changes;</li><li>runs <code>task docs:generate</code>;</li><li>runs <code>task docs:check</code>;</li><li>refuses the commit when generated changes are unstaged or validation fails.</li></ol><p>CI:</p><ol><li>runs <code>task docs:check</code> without modifying committed output;</li><li>builds the static site;</li><li>publishes only from the approved branch or release;</li><li>never treats generated data as handwritten source.</li></ol><p>A commit MUST NOT be created while generated documentation is stale.</p><h2 id="validation-requirements" tabindex="-1">Validation requirements <a class="header-anchor" href="#validation-requirements" aria-label="Permalink to &quot;Validation requirements&quot;">​</a></h2><p>Generator tests cover:</p><ul><li>stable ordering;</li><li>schema reference rewriting;</li><li><code>$defs</code> flattening;</li><li>duplicate IDs and routes;</li><li>registry coverage;</li><li>comments and descriptions;</li><li>secret redaction;</li><li>obsolete-file removal;</li><li>byte-identical repeated generation;</li><li>check-mode diagnostics.</li></ul><p>Site validation covers:</p><ul><li>frozen dependency installation;</li><li>VitePress production build;</li><li>dead internal links;</li><li>generated-data loader imports;</li><li>expected output routes;</li><li>absence of unrelated product names and URLs;</li><li>absence of committed build artifacts.</li></ul><p>The root module remains free of generator-only dependencies.</p><h2 id="completion-criteria" tabindex="-1">Completion criteria <a class="header-anchor" href="#completion-criteria" aria-label="Permalink to &quot;Completion criteria&quot;">​</a></h2><p>The documentation migration is complete when:</p><ul><li><code>tools</code> belongs to Archie and builds against the working tree;</li><li><code>docsgen</code> consumes Archie-owned registries and types;</li><li>AsyncAPI output describes Archie;</li><li>required reference categories are generated as committed deterministic data;</li><li><code>catalog.json</code> matches the generated definitions and rendered routes;</li><li>VitePress components and templates render the generated data;</li><li>two consecutive generations are byte-identical;</li><li><code>docsgen check</code> detects changed, missing, and obsolete artifacts;</li><li>VitePress contains only intentional Archie content;</li><li>build artifacts and installed dependencies are absent from source control;</li><li><code>task docs:serve</code> supports local authoring;</li><li><code>task docs:build</code> produces the deployable site;</li><li><code>task check</code> blocks stale or broken documentation;</li><li>GitHub Pages publishes the verified VitePress artifact.</li></ul><h2 id="implementation-references" tabindex="-1">Implementation references <a class="header-anchor" href="#implementaLine truncated
@@ -1 +0,0 @@
import{_ as a,o as i,c as s,a2 as t}from"./chunks/framework.BWuWLRhz.js";const u=JSON.parse('{"title":"Generated Documentation and Documentation Site","description":"","frontmatter":{},"headers":[],"relativePath":"architecture/generated-documentation.md","filePath":"architecture/generated-documentation.md","lastUpdated":null}'),n={name:"architecture/generated-documentation.md"};function l(o,e,r,d,p,c){return i(),s("div",null,[...e[0]||(e[0]=[t("",118)])])}const g=a(n,[["render",l]]);export{u as __pageData,g as default};
@@ -1,9 +0,0 @@
import{_ as t,o as i,c as n,a2 as a}from"./chunks/framework.BWuWLRhz.js";const h=JSON.parse('{"title":"Identity","description":"","frontmatter":{},"headers":[],"relativePath":"architecture/identity.md","filePath":"architecture/identity.md","lastUpdated":null}'),r={name:"architecture/identity.md"};function s(o,e,d,c,l,p){return i(),n("div",null,[...e[0]||(e[0]=[a(`<h1 id="identity" tabindex="-1">Identity <a class="header-anchor" href="#identity" aria-label="Permalink to &quot;Identity&quot;">​</a></h1><p><strong>Status:</strong> Approved foundation; lifecycle details are deferred<br><strong>Date:</strong> 2026-07-28<br><strong>Beads issue:</strong> <code>archie-core-5d7</code></p><h2 id="purpose" tabindex="-1">Purpose <a class="header-anchor" href="#purpose" aria-label="Permalink to &quot;Purpose&quot;">​</a></h2><p>Identity answers which persistent actor owns or performed an action. It supplies stable cross-domain attribution and lifecycle semantics.</p><p>Identity kinds include:</p><ul><li>the Archie system identity, such as <code>System</code> or <code>archied</code>;</li><li>agent or bot identities;</li><li>service-account identities;</li><li>future user identities.</li></ul><p>A user is another kind of identity rather than a separate foundation concept.</p><h2 id="ownership" tabindex="-1">Ownership <a class="header-anchor" href="#ownership" aria-label="Permalink to &quot;Ownership&quot;">​</a></h2><p><code>internal/domain/identity</code> owns:</p><ul><li>immutable canonical <code>IdentityID</code> values;</li><li>identity kind;</li><li>lifecycle state;</li><li>ownership and attribution semantics;</li><li>identity-related commands and events.</li></ul><p>Domains may record an identity reference on their own state and events when ownership or attribution is required. They MUST NOT receive a complete per-identity application configuration bundle.</p><p>Persona and communication style are separate from identity.</p><p>Every Agent has its own immutable acting <code>IdentityID</code>. Agent actions use that identity for ownership and attribution in the same way an organisation records which user accessed a resource, changed a permission, or performed another auditable action.</p><p>Agent and Identity remain separate aggregates. Identity supplies the stable actor reference; Agent owns assistant behaviour, memory, specialisation, conversations, and capability context.</p><p>Agent identities MUST NOT be shared between Agents. Automated WorkflowExecutions MAY eventually act through a dedicated service-account identity when a specific unattended automation requires it. Such use is an explicit execution decision and audit principal, not the default for Agents or a substitute for recording the initiating user when one exists.</p><p>A Workflow is owned by an IdentityID and executes as its owner by default. Future delegated execution MAY explicitly assign a different <code>RunAsIdentityID</code>, including a user or service-account identity. Ownership, effective execution identity, initiating identity, and delegation provenance remain distinct audit facts.</p><h2 id="canonical-identity" tabindex="-1">Canonical identity <a class="header-anchor" href="#canonical-identity" aria-label="Permalink to &quot;Canonical identity&quot;">​</a></h2><p>Every identity has an immutable <code>IdentityID</code>. It is the only value used for cross-domain ownership, attribution, routing, persistence, commands, and events.</p><p>Identity kind is explicit:</p><ul><li>system;</li><li>bot;</li><li>service account;</li><li>user.</li></ul><p>Display names are mutable and MUST NOT be used as identifiers. Forge usernames, channel bot names, Git authors, provider account names, and other external identifiers are bindings associated with an identity rather than identity itself.</p><p><code>System</code> is represented by a real identity and <code>IdentityID</code>. The empty string MUST NOT retain special meaning as a legacy system identity.</p><p>Configuration refers to identities by <code>IdentityID</code> and supplies external bindings and capability settings separately. Renaming an identity or changing an external account MUST NOT change ownership or historical attribution.</p><h2 id="persistence" tabindex="-1">Persistence <a class="header-anchor" href="#persistence" aria-label="Permalink to &quot;Persistence&quot;">​</a></h2><p>Identity records are durable domain state. The Identity domain&#39;s repository is the source of truth; infrastructure implements its persistence contract.</p><p>Configuration MAY bootstrap a missing identity through an explicit, audited creation operation and MAY propose runtime capability bindings for an existing <code>IdentityID</code>. Configuration is not the identity registry.</p><p>Omitting an identity from configuration stops assembling the omitted runtime capabilities. It MUST NOT delete the identity record, erase history, or make historical references unresolvable.</p><p>Disabling or retiring an i Line truncated
<span class="line"><span>active -&gt; suspended</span></span>
<span class="line"><span>suspended -&gt; active</span></span>
<span class="line"><span>active -&gt; retired</span></span>
<span class="line"><span>suspended -&gt; retired</span></span></code></pre></div><p><code>retired</code> has no outgoing transition.</p><p>Capability health is separate from identity lifecycle. Forge, model, channel, workspace, and other bindings report health independently. An active identity may be partially degraded without becoming suspended or retired. Runtime supervision isolates and restores affected bindings through the safe-change and recovery protocol.</p><h2 id="system-identity" tabindex="-1">System identity <a class="header-anchor" href="#system-identity" aria-label="Permalink to &quot;System identity&quot;">​</a></h2><p>Archie has exactly one built-in system identity. It is created during initial store bootstrap, is strictly always active, and cannot be suspended or retired. Its <code>IdentityID</code> and kind are immutable.</p><p>Startup, migration, supervision, remediation, and rollback actions performed by the application use the system identity. The system identity MUST NOT be delegated to individual identities. Every user, bot, service account, or other actor mutation records the identity that actually performed it.</p><p>System capabilities may independently become unhealthy or unavailable without changing the system identity.</p><h2 id="target-placement-and-contracts" tabindex="-1">Target placement and contracts <a class="header-anchor" href="#target-placement-and-contracts" aria-label="Permalink to &quot;Target placement and contracts&quot;">​</a></h2><p>The Identity domain lives at <code>internal/domain/identity</code>.</p><p>It owns:</p><ul><li><code>IdentityID</code>, identity kind, display name, lifecycle, version, and audit timestamps;</li><li>create, rename, suspend, reactivate, and retire commands;</li><li>corresponding lifecycle events;</li><li>the repository contract required for durable identity records;</li><li>lookup of current and historical identities.</li></ul><p>External account bindings and capability settings remain with the domains that use them and reference <code>IdentityID</code>.</p><h2 id="migration-constraints" tabindex="-1">Migration constraints <a class="header-anchor" href="#migration-constraints" aria-label="Permalink to &quot;Migration constraints&quot;">​</a></h2><p>Migration from the current string model MUST:</p><ul><li>bootstrap the permanent system identity;</li><li>assign stable IDs to configured identities without losing their names;</li><li>replace empty-string legacy ownership with the system identity;</li><li>migrate tasks and sessions to canonical identity references;</li><li>include identity where task uniqueness and transport deduplication require independent ownership;</li><li>route container RPC through the task owner&#39;s capability bindings;</li><li>retain historical resolution after rename, suspension, or retirement;</li><li>remove identity-string equality from authentication or access semantics.</li></ul><p>This completes the foundation required to restructure the current Identity behaviour. Exact storage schemas and Go method signatures belong to implementation design, not this architecture review.</p><h2 id="lifecycle-1" tabindex="-1">Lifecycle <a class="header-anchor" href="#lifecycle-1" aria-label="Permalink to &quot;Lifecycle&quot;">​</a></h2><p>Identity lifecycle is deliberately small:</p><ul><li><code>active</code>: may participate in runtime composition;</li><li><code>suspended</code>: deliberately prevented from initiating new work while ownership and history remain;</li><li><code>retired</code>: terminal, unable to initiate work, and permanently retained for attribution.</li></ul><p>Allowed transitions are:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>create -&gt; active</span></span>
<span class="line"><span>active -&gt; suspended</span></span>
<span class="line"><span>suspended -&gt; active</span></span>
<span class="line"><span>active -&gt; retired</span></span>
<span class="line"><span>suspended -&gt; retired</span></span></code></pre></div><p><code>retired</code> has no outgoing transition.</p><p>Capability health is separate from identity lifecycle. Forge, model, channel, workspace, and other bindings report health independently. An active identity may be partially degraded without becoming suspended or retired. Runtime supervision isolates and restores affected bindings through the safe-change and recovery protocol.</p><h2 id="explicit-non-responsibilities" tabindex="-1">Explicit non-responsibilities <a class="header-anchor" href="#explicit-non-responsibilities" aria-label="Permalink to &quot;Explicit non-responsibilities&quot;">​</a></h2><p>Identity is not authentication and is not access control.</p><p>The current architecture does not require authentication or authorization. Those capabilities MAY be introduced later if deployment or product needs justify them. They MUST remain separate from the identity model.</p><p>An identity reference therefore proves attribution within Archie&#39;s trusted system model; it does not by itself prove credentials or permission.</p><h2 id="per-identity-configuration" tabindex="-1">Per-identity configuration <a class="header-anchor" href="#per-identity-configuration" aria-label="Permalink to &quot;Per-identity configuration&quot;">​</a></h2><p>Values selected for an identity remain external configuration values. At composition time they are split into the runtime settings owned by the affected domains and correlated by identity reference.</p><p>The existing <code>IdentityConfig</code> aggregate MUST be dissolved. Forge accounts, repositories, models, providers, workspace behaviour, polling, budgets, notifications, and transport namespaces retain their respective owners.</p><h2 id="audit" tabindex="-1">Audit <a class="header-anchor" href="#audit" aria-label="Permalink to &quot;Audit&quot;">​</a></h2><p>Configuration changes and other state changes are actions attributed to an identity. System-initiated changes use the system identity. Their audit records MUST preserve the acting identity, the target, and the resulting change.</p><p>The command ownership and persistence mechanism for configuration changes is a separate configuration-management decision.</p><h2 id="current-implementation" tabindex="-1">Current implementation <a class="header-anchor" href="#current-implementation" aria-label="Permalink to &quot;Current implementation&quot;">​</a></h2><p>Identity is not currently implemented as a domain. It is a collection of string fields and process-local associations:</p><ul><li><code>config.IdentityConfig.Name</code> is the daemon routing key.</li><li><code>config.IdentityConfig.BotUser</code> is the external forge and Git author name.</li><li><code>daemon.IdentityRunner</code> bundles the configured name with a forge client, worktree manager, repository list, configuration subset, logger, and polling goroutine.</li><li><code>store.Task.Identity</code> persists the configured name on tasks.</li><li>NATS task messages copy the same configured name.</li><li>gateway routing accepts an identity name and uses it to select a repository profile.</li><li>gateway sessions persist <code>BotUser</code>, not the configured identity name.</li></ul><p>There is no identity registry, identity record, identity lifecycle state, identity persistence, or identity command/event model. Removing an identity from configuration makes existing task ownership unresolvable.</p><p>An empty identity string selects the legacy single-identity path. This gives the empty string behavioural meaning rather than representing a real system identity.</p><h2 id="current-enforcement-and-isolation" tabindex="-1">Current enforcement and isolation <a class="header-anchor" href="#current-enforcement-and-isolation" aria-label="Permalink to &quot;Current enforcement and isolation&quot;">​</a></h2><p>The current implementation uses identity equality as an authorization check for chat task approval and cancellation. This conflicts with the approved rule that identity is attribution rather than authentication or access control and must be reassigned to an appropriate task-ownership or future access policy.</p><p>Focused tests verify that:</p><ul><li>a task resolves the forge client and repository list associated with its configured identity name;</li><li>cross-identity repository profiles do not leak;</li><li>chat task creation propagates the selected identity;</li><li>task and NellDB persistence retain the identity string;</li><li>chat task control rejects a different identity string.</li></ul><h2 id="current-hazards" tabindex="-1">Current hazards <a class="header-anchor" href="#current-hazards" aria-label="Permalink to &quot;Current hazards&quot;">​</a></h2><ul><li>SQLite task uniqueness is <code>(owner, repo, issue_number)</code> and excludes identity. Two identities discovering the same forge issue cannot own distinct task records.</li><li>NATS deduplication Line truncated
@@ -1 +0,0 @@
import{_ as t,o as i,c as n,a2 as a}from"./chunks/framework.BWuWLRhz.js";const h=JSON.parse('{"title":"Identity","description":"","frontmatter":{},"headers":[],"relativePath":"architecture/identity.md","filePath":"architecture/identity.md","lastUpdated":null}'),r={name:"architecture/identity.md"};function s(o,e,d,c,l,p){return i(),n("div",null,[...e[0]||(e[0]=[a("",77)])])}const y=t(r,[["render",s]]);export{h as __pageData,y as default};
@@ -1 +0,0 @@
import{_ as i,o as t,c as a,a2 as n}from"./chunks/framework.BWuWLRhz.js";const p=JSON.parse('{"title":"Architecture","description":"","frontmatter":{},"headers":[],"relativePath":"architecture/index.md","filePath":"architecture/index.md","lastUpdated":null}'),r={name:"architecture/index.md"};function s(o,e,c,l,d,u){return t(),a("div",null,[...e[0]||(e[0]=[n('<h1 id="architecture" tabindex="-1">Architecture <a class="header-anchor" href="#architecture" aria-label="Permalink to &quot;Architecture&quot;">​</a></h1><p>Archie is a personal agent platform built around six domain boundaries:</p><ul><li>Identity tracks users and other actors responsible for actions.</li><li>Agent owns persistent assistants, specialisation, and continuity.</li><li>Messaging owns conversations, messages, branches, and channel correlation.</li><li>Workflow owns reusable, versioned behaviour definitions and their executions.</li><li>Work Intake admits optional durable work without constraining ordinary agent conversation or direct capability use.</li><li>Plugin owns generic extension discovery and lifecycle; each capability family owns its typed plugin contract.</li></ul><p>The detailed architecture and migration decisions are maintained under <code>docs/architecture/</code> in the repository while this generated site is being assembled.</p>',4)])])}const _=i(r,[["render",s]]);export{p as __pageData,_ as default};
@@ -1 +0,0 @@
import{_ as i,o as t,c as a,a2 as n}from"./chunks/framework.BWuWLRhz.js";const p=JSON.parse('{"title":"Architecture","description":"","frontmatter":{},"headers":[],"relativePath":"architecture/index.md","filePath":"architecture/index.md","lastUpdated":null}'),r={name:"architecture/index.md"};function s(o,e,c,l,d,u){return t(),a("div",null,[...e[0]||(e[0]=[n("",4)])])}const _=i(r,[["render",s]]);export{p as __pageData,_ as default};
@@ -1,6 +0,0 @@
import{_ as a,o as t,c as n,a2 as i}from"./chunks/framework.BWuWLRhz.js";const p=JSON.parse('{"title":"Messaging and Work Intake","description":"","frontmatter":{},"headers":[],"relativePath":"architecture/messaging-and-work-intake.md","filePath":"architecture/messaging-and-work-intake.md","lastUpdated":null}'),o={name:"architecture/messaging-and-work-intake.md"};function s(r,e,l,c,d,u){return t(),n("div",null,[...e[0]||(e[0]=[i(`<h1 id="messaging-and-work-intake" tabindex="-1">Messaging and Work Intake <a class="header-anchor" href="#messaging-and-work-intake" aria-label="Permalink to &quot;Messaging and Work Intake&quot;">​</a></h1><p><strong>Status:</strong> Current state researched; foundation decisions in progress<br><strong>Date:</strong> 2026-07-28<br><strong>Beads issue:</strong> <code>archie-core-5d7</code></p><h2 id="purpose" tabindex="-1">Purpose <a class="header-anchor" href="#purpose" aria-label="Permalink to &quot;Purpose&quot;">​</a></h2><p>Archie is a personal assistant and general agentic system. Its interactions include conversation, questions, notes, reminders, goals, message handling, troubleshooting, infrastructure operations, server management, source changes, and open-ended future capabilities.</p><p>A message to an agent is therefore not inherently a work request, and invoking an agent is not inherently a WorkflowExecution.</p><p>Messaging and work intake are separate from the Agent System&#39;s durable workflow execution model:</p><ul><li>messaging preserves interactions with people and external systems;</li><li>an agent turn interprets and responds to an interaction using its available capabilities;</li><li>work intake handles the optional promotion of an interaction into durable, workflow-backed work;</li><li>the Agent System owns Workflow definitions and creates WorkflowExecutions.</li></ul><p>Forge issues, Jira issues, Telegram messages, emails, webhooks, and future channels remain peer external message or artifact sources. None becomes an execution model merely because it can lead to work.</p><h2 id="confirmed-boundary" tabindex="-1">Confirmed boundary <a class="header-anchor" href="#confirmed-boundary" aria-label="Permalink to &quot;Confirmed boundary&quot;">​</a></h2><p>Work intake MUST NOT create a WorkflowExecution directly.</p><p>Inbound interactions normally route to the Agent selected by the channel binding. The selected Agent retains its own memory, user knowledge, conversation continuity, specialisation, and capability context. This continuity is independent of the underlying model or provider.</p><p>Each selected Agent acts through its own immutable IdentityID. Interaction and resulting action records preserve both that acting identity and the initiating user identity when one exists.</p><p>Agent memory is private by default. Interaction context MAY additionally use user-wide memory and intentionally global shared memory, but another Agent&#39;s agent-wide memory is not part of the selected Agent&#39;s context.</p><p>Multiple users may interact with the same Agent. The channel binding and inbound message MUST resolve both AgentID and initiating User IdentityID before conversation or memory context is loaded. Sharing an Agent MUST NOT implicitly share one user&#39;s private memory with another user.</p><p>An interaction may assemble memory from four scopes: global shared, the selected Agent&#39;s agent-wide memory, the initiating user&#39;s authorized user-wide memory, and the private Agent-user relationship memory addressed by both IDs.</p><h2 id="conversation-identity" tabindex="-1">Conversation identity <a class="header-anchor" href="#conversation-identity" aria-label="Permalink to &quot;Conversation identity&quot;">​</a></h2><p>Every conversation is identified by the complete tuple:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>AgentID</span></span>
<span class="line"><span>+ UserIdentityID</span></span>
<span class="line"><span>+ ChannelBindingID</span></span>
<span class="line"><span>+ ExternalConversationID</span></span>
<span class="line"><span>+ ThreadID</span></span></code></pre></div><p><code>ThreadID</code> has an explicit empty value for channels without threads. No element of this key may be replaced by a display name, configured bot username, channel type, or other mutable label.</p><p>Agent and user memory continue across conversations according to their memory scope. Immediate conversation history and delivery correlation remain isolated to the identified channel conversation or thread. Moving between Telegram, email, or another channel does not create a new Agent or user, but it does create a distinct conversation unless an explicit linking operation relates them.</p><p>Conversation and message events support projections for channel-entry metrics, use cases, volumes, outcomes, latency, capability usage, and other product or operational analysis. Metrics are derived read models; they MUST NOT become mutable counters embedded in the conversation aggregate or change message routing semantics.</p><h2 id="canonical-messages" tabindex="-1">Canonical messages <a class="header-anchor" href="#canonical-messages" aria-label="Permalink to &quot;Canonical messages&quot;">​</a></h2><p>Every inbound, assistant, tool-call, and tool-result message has an immutable application-generated MessageID. Platform identifiers are external correlation, not substitutes for the canonical ID.</p><p>Messages are addressable because an interaction is more than text. A message may contain assistant content, reasoning data subject to its retention policy, one or more tool calls, a tool result with authoritative execution metadata, attachments, reply relationships, edits, or other typed content. Stable MessageIDs also allow sessions to branch from an exact prior point.</p><p>The canonical session and message implementation must supply:</p><ul><li>application-generated stable message IDs;</li><li>user, assistant, and tool roles;</li><li>assistant tool calls and correlated tool-result messages;</li><li>authoritative tool-result status, timing, error, truncation, and size metadata;</li><li>session lifecycle and active-request state;</li><li>session-to-agent-instance and parent-session lineage;</li><li>durable SQLite round trips and timestamp validation.</li></ul><p>These semantics must use the confirmed Agent, user, channel-binding, and conversation ownership model.</p><p>The canonical message store MUST preserve messages as immutable records and represent later edits, deletions, and branches through related records or events.</p><p>Archie requires exact branch-point correlation using stable MessageIDs.</p><h2 id="conversation-branches" tabindex="-1">Conversation branches <a class="header-anchor" href="#conversation-branches" aria-label="Permalink to &quot;Conversation branches&quot;">​</a></h2><p>A branch is a continuation of a previous conversation at an exact message. A child conversation records:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>ParentConversationID</span></span>
<span class="line"><span>ForkMessageID</span></span></code></pre></div><p>Messages remain an append-only linear sequence within each conversation. The child&#39;s effective initial context is the parent&#39;s history through <code>ForkMessageID</code>; messages after that point in the parent are not inherited.</p><p>After the fork, parent and child are isolated:</p><ul><li>child messages, tool calls, tool results, capability actions, and errors do not appear in the parent conversation;</li><li>later parent messages do not silently enter the child;</li><li>returning to the parent resumes its unchanged history;</li><li>the child may itself be branched using the same rules;</li><li>branch lineage remains queryable for navigation, audit, and metrics.</li></ul><p>This supports building substantial context about a subject and then performing one or more contextual subtasks without polluting the original conversation. For example, a user may branch from a project discussion, create Jira issues in the child using inherited context, and then return to the project discussion without adding the Jira tool transcript to the parent.</p><p>Branching does not copy mutable message rows. History is resolved through the immutable parent conversation and fork MessageID, followed by the child&#39;s own message sequence.</p><p>Branch isolation applies to conversation history, not to Agent learning or memory. A memory action performed in a branch has exactly the same semantics as the same action performed in any other conversation. It writes to its selected global, agent-wide, user-wide, or Agent-user relationship scope.</p><p>Memory provenance MAY retain the source ConversationID and MessageIDs for explanation and audit. Retrieval and effect are determined by memory scope and access rules, not by the conversation from which the memory originated. Returning to a parent does not insert the child&#39;s tool transcript into the parent history, but scoped memories learned in the child remain available to future retrieval wherever that scope is visible.</p><p>Changing sessions or branching therefore controls immediate conversational context without preventing the Agent from learning durable knowledge.</p><h2 id="target-ownership" tabindex="-1">Target ownership <a class="header-anchor" href="#target-ownership" aria-label="Permalink to &quot;Target ownership&quot;">​</a></h2><p>The Messaging domain lives at <code>internal/domain/messaging</code>. It owns:</p><ul><li>canonical Messages and typed message content;</li><li>Conversations, branches, and lineage;</li><li>channel bindings and external source correlation;</li><li>replies, acknowledgements, and outbound delivery attempts;</li><li>message and conversation lifecycle events;</li><li>domain-defined repository and delivery service contracts;</li><li>projections required for conversation navigation and metrics.</li></ul><p>Work intake is a separate cohesive domain at <code>internal/domain/workintake</code>. It owns admission, validation, deterministic routing, and accepted work requests for the optional transition into durable workflow-backed execution.</p><p>Telegram, email, webhook, forge, Jira, and future messaging systems are infrastructure adapters implementing Messaging contracts. They are users of the domain; they do not own Messages, Conversations, work admission, or WorkflowExecution semantics.</p><p>The Agent decides whether an ordinary interaction is answered directly, uses a capability, changes or retrieves Agent-owned information, or proposes durable workflow-backed work.</p><p>Explicitly configured automation MAY enter work intake without a conversational Agent turn when the external trigger and admission rule already unambiguously request durable work. This avoids spending an LLM turn to rediscover a deterministic routing decision.</p><p>When an interaction requires durable workflow-backed execution:</p><ol><li>a channel adapter produces a channel-neutral inbound message;</li><li>the acting agent handles or interprets the interaction;</li><li>work intake validates, admits, and routes a proposed work request;</li><li>work intake emits an accepted work request with its source correlation, acting identity, requested outcome, inputs, and routing evidence;</li><li>the Agent System consumes that request, selects a specific Workflow version, and creates the WorkflowExecution.</li></ol><p>The accepted work request is a cross-domain handoff, not an alternate execution aggregate. The Agent System is the sole authority that creates a valid WorkflowExecution.</p><p>An interaction MAY instead be completed directly by an agent turn, delegated to a tool or capability, recorded as a note or reminder, answered conversationally, or retained for later context. Those paths MUST NOT require a Workflow or WorkflowExecution.</p><p>A Workflow MAY add reusable, versioned structure to any of those behaviours. Scheduled personal-assistant routines, message triage, reminders, infrastructure operLine truncated
@@ -1 +0,0 @@
import{_ as a,o as t,c as n,a2 as i}from"./chunks/framework.BWuWLRhz.js";const p=JSON.parse('{"title":"Messaging and Work Intake","description":"","frontmatter":{},"headers":[],"relativePath":"architecture/messaging-and-work-intake.md","filePath":"architecture/messaging-and-work-intake.md","lastUpdated":null}'),o={name:"architecture/messaging-and-work-intake.md"};function s(r,e,l,c,d,u){return t(),n("div",null,[...e[0]||(e[0]=[i("",62)])])}const g=a(o,[["render",s]]);export{p as __pageData,g as default};
@@ -1,15 +0,0 @@
import{_ as i,o as a,c as n,a2 as t}from"./chunks/framework.BWuWLRhz.js";const u=JSON.parse('{"title":"Architecture Migration Decisions","description":"","frontmatter":{},"headers":[],"relativePath":"architecture/migration-decisions.md","filePath":"architecture/migration-decisions.md","lastUpdated":null}'),o={name:"architecture/migration-decisions.md"};function s(r,e,l,c,d,p){return a(),n("div",null,[...e[0]||(e[0]=[t(`<h1 id="architecture-migration-decisions" tabindex="-1">Architecture Migration Decisions <a class="header-anchor" href="#architecture-migration-decisions" aria-label="Permalink to &quot;Architecture Migration Decisions&quot;">​</a></h1><p><strong>Status:</strong> Active migration inventory<br><strong>Date:</strong> 2026-07-28<br><strong>Beads issue:</strong> <code>archie-core-5d7</code></p><h2 id="purpose" tabindex="-1">Purpose <a class="header-anchor" href="#purpose" aria-label="Permalink to &quot;Purpose&quot;">​</a></h2><p>This document records what remains to be decided before Archie&#39;s current implementation can be migrated into the approved domain-oriented structure.</p><p>The product and core domain model are not being redesigned. Existing Archie behaviour and the existing session implementation are the migration baseline. Remaining decisions MUST be grounded in current packages, consumers, tests, persistence, and runtime wiring.</p><h2 id="confirmed-domain-packages" tabindex="-1">Confirmed domain packages <a class="header-anchor" href="#confirmed-domain-packages" aria-label="Permalink to &quot;Confirmed domain packages&quot;">​</a></h2><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>internal/domain/</span></span>
<span class="line"><span> identity/</span></span>
<span class="line"><span> agent/</span></span>
<span class="line"><span> workflow/</span></span>
<span class="line"><span> messaging/</span></span>
<span class="line"><span> workintake/</span></span>
<span class="line"><span> plugin/</span></span></code></pre></div><ul><li><code>identity</code> owns persistent actors, lifecycle, ownership, attribution, and audit identity.</li><li><code>agent</code> owns persistent assistants, specialisation, instructions, model-independent continuity, capability context, and associations with identity and memory.</li><li><code>workflow</code> is a separate domain. It owns reusable, versioned Workflow definitions, WorkflowSteps, WorkflowExecutions, StepExecutions, Attempts, outcomes, and typed Workflow plugin contracts.</li><li><code>messaging</code> owns canonical Messages, Conversations, branches, channel and source correlation, replies, acknowledgements, delivery attempts, events, and projections.</li><li><code>workintake</code> owns admission, validation, deterministic routing, and accepted work requests for the optional transition into durable workflow-backed execution.</li><li><code>plugin</code> owns generic plugin identity, discovery, compatibility, and lifecycle mechanics. It remains metadata-only; capability semantics and typed registration belong to the owning domain.</li></ul><p>Memory&#39;s final package placement remains undecided pending focused review of the existing implementation.</p><p>The following are approved shared or composition packages, not domains:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>internal/eventbus/</span></span>
<span class="line"><span>internal/policy/</span></span>
<span class="line"><span>internal/infrastructure/</span></span>
<span class="line"><span>internal/app/archied/</span></span>
<span class="line"><span>internal/app/agentworker/</span></span></code></pre></div><h2 id="remaining-migration-decisions" tabindex="-1">Remaining migration decisions <a class="header-anchor" href="#remaining-migration-decisions" aria-label="Permalink to &quot;Remaining migration decisions&quot;">​</a></h2><h3 id="_1-complete-package-destination-map" tabindex="-1">1. Complete package destination map <a class="header-anchor" href="#_1-complete-package-destination-map" aria-label="Permalink to &quot;1. Complete package destination map&quot;">​</a></h3><p>Every current package MUST receive one explicit disposition:</p><ul><li>move into a confirmed domain;</li><li>move under infrastructure as an implementation of a domain-owned contract;</li><li>move into application composition;</li><li>merge with an identified duplicate;</li><li>remain as an approved shared application contract;</li><li>move to a plugin, extra, deployment, example, or generated artifact;</li><li>be deleted after its replacement is proven.</li></ul><p>The largest unreviewed areas include memory, tools and capabilities, workspace and worktree behaviour, gates, storage, events, web UI, containers, RPC packages, release management, and scheduling.</p><p>The destination matrix MUST name the behaviour owner, target path, dependencies to remove, state and contracts to preserve, migration prerequisites, and deletion criteria.</p><h3 id="_2-session-and-messaging-migration" tabindex="-1">2. Session and Messaging migration <a class="header-anchor" href="#_2-session-and-messaging-migration" aria-label="Permalink to &quot;2. Session and Messaging migration&quot;">​</a></h3><p>The existing session implementation is the migration baseline. The migration must decide:</p><ul><li>which session and message components are retained or adapted;</li><li>how Agent, user, channel, Conversation, and branch ownership are added;</li><li>how Archie&#39;s parallel gateway session implementation is replaced;</li><li>how canonical Messages become immutable persisted records;</li><li>how existing NellDB sessions and messages are migrated;</li><li>how outbound delivery, retry, acknowledgement, deduplication, and failure semantics are represented;</li><li>how current Telegram, email, webhook, forge, and Jira integrations migrate to Messaging infrastructure adapters.</li></ul><p>The following are already decided and MUST NOT be reopened without contradictory implementation evidence:</p><ul><li>the composite Conversation identity;</li><li>immutable MessageIDs;</li><li>typed tool-call and tool-result messages;</li><li>exact branch lineage through ParentConversationID and ForkMessageID;</li><li>parent and child transcript isolation;</li><li>normal scoped-memory behaviour regardless of the originating Conversation;</li><li>Messaging and Work Intake ownership.</li></ul><h3 id="_3-identity-data-migration" tabindex="-1">3. Identity data migration <a class="header-anchor" href="#_3-identity-data-migration" aria-label="Permalink to &quot;3. Identity data migration&quot;">​</a></h3><p>The migration must define:</p><ul><li>the durable identity schema and repository implementation;</li><li>bootstrap of the permanent system identity;</li><li>stable IdentityIDs for existing configured Agents;</li><li>migration from configured identity names, empty-string ownership, and bot usernames;</li><li>preservation of historical attribution;</li><li>identity-aware uniqueness and transport deduplication;</li><li>correction of container and RPC capability resolution so execution uses the owning identity&#39;s bindings;</li><li>removal of identity-string equality from access-control behaviour.</li></ul><p>Exact schema and method signatures are implementation decisions. The approved Identity lifecycle and attribution semantics are fixed migration constraints.</p><h3 id="_4-workflow-migration" tabindex="-1">4. Workflow migration <a class="header-anchor" href="#_4-workflow-migration" aria-label="Permalink to &quot;4. Workflow migration&quot;">​</a></h3><p>The current implementation must be transformed deliberately:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>store.Task -&gt; WorkflowExecution</span></span>
<span class="line"><span>mutable Stage -&gt; StepExecution history</span></span>
<span class="line"><span>RetryCount / Attempt -&gt; Attempt records</span></span>
<span class="line"><span>workflow.Registry -&gt; versioned Workflow definitions</span></span>
<span class="line"><span>current stages -&gt; WorkflowStep definitions or Workflow plugins</span></span></code></pre></div><p>The migration must decide:</p><ul><li>Workflow definition and version persistence;</li><li>the smallest accepted-work-request contract consumed from Work Intake;</li><li>the enforced WorkflowExecution state machine;</li><li>atomic state and domain-event persistence;</li><li>migration of existing task rows and transition history;</li><li>disposition of current skill, Yaegi, and stage-plugin implementations;</li><li>the versioned worker-handoff contract;</li><li>scheduler, claim, retry, crash-recovery, and waiting-human cutover.</li></ul><p>Workflow remains a separate domain from Agent. A user or Agent may define or invoke a Workflow, but Workflow semantics and plugins remain Workflow-owned.</p><h3 id="_5-memory-placement-and-storage" tabindex="-1">5. Memory placement and storage <a class="header-anchor" href="#_5-memory-placement-and-storage" aria-label="Permalink to &quot;5. Memory placement and storage&quot;">​</a></h3><p>The four required scopes are fixed:</p><ul><li>global shared;</li><li>Agent-wide;</li><li>user-wide;</li><li>Agent-user relationship.</li></ul><p>A focused review of <code>internal/memory</code>, its providers, consumers, persistence, and tests must decide:</p><ul><li><code>internal/domain/memory</code> versus ownership within the Agent domain;</li><li>the authoritative memory record and revision model;</li><li>provider and infrastructure boundaries;</li><li>retrieval and access enforcement;</li><li>migration of existing memory data;</li><li>provenance representation.</li></ul><p>Conversation branches do not create another memory scope. A memory action has the same scoped effect regardless of which Conversation originated it.</p><h3 id="_6-runtime-and-process-boundaries" tabindex="-1">6. Runtime and process boundaries <a class="header-anchor" href="#_6-runtime-and-process-boundaries" aria-label="Permalink to &quot;6. Runtime and process boundaries&quot;">​</a></h3><p>The migration must decide which current execution paths survive:</p><ul><li>in-process execution;</li><li><code>archie-agent</code> subprocess execution;</li><li>NATS worker execution;</li><li>container isolation;</li><li>forge, store, and worktree RPC services.</li></ul><p>The source architecture remains a modular monolith. A retained process boundary requires a concrete security-isolation, failure-containment, scaling, or operational justification. Possible future extraction is insufficient.</p><h3 id="_7-shared-mechanics" tabindex="-1">7. Shared mechanics <a class="header-anchor" href="#_7-shared-mechanics" aria-label="Permalink to &quot;7. Shared mechanics&quot;">​</a></h3><p>The following cross-domain mechanics require exact contracts before dependent packages migrate:</p><ul><li>event-bus delivery and failure semantics;</li><li>policy evaluation API, composition, and precedence;</li><li>configuration candidate preparation, health validation, atomic promotion, observation, and rollback;</li><li>service-specific health, bounded remediation, isolation, and escalation;</li><li>changelog association and grouping.</li></ul><p>These shared mechanisms do not acquire ownership of domain meaning. Domains continue to own their commands, events, policies, settings, and consequences.</p><p>The copied Go <code>specgen</code> and VitePress documentation pipeline, output placement, developer commands, drift checking, hook sequence, and CI sequence are defined in <code>generated-documentation.md</code>. Adapting the copied files, implementing Archie&#39;s normalized documentation model and page renderers, and cutting <code>docs</code> over to its final location remain migration work rather than open product architecture.</p><h3 id="_8-cutover-sequence" tabindex="-1">8. Cutover sequence <a class="header-anchor" href="#_8-cutover-sequence" aria-label="Permalink to &quot;8. Cutover sequence&quot;">​</a></h3><p>The final migration plan must order:</p><ul><li>compatibility adapters;</li><li>schema migrations and data backfills;</li><li>any required dual-read or transitional paths;</li><li>domain-by-domain package replacement;</li><li>production wiring changes;</li><li>legacy package removal;</li><li>architecture tests preventing dependency regression;</li><li>focused, integration, race, and full quality gates.</li></ul><p>Each legacy package requires objective removal criteria. No compatibility path may become an indefinite second implementation.</p><h2 id="completion-criteria" tabindex="-1">Completion criteria <a class="header-anchor" href="#completion-criteria" aria-label="Permalink to &quot;Completion criteria&quot;">​</a></h2><p>Migration design is complete when:</p><ul><li>every current package has one approved owner and destination;</li><li>every mutable record has one authoritative owner and migration path;</li><li>all external and cross-process contracts have versioned owners;</li><li>existinLine truncated
@@ -1 +0,0 @@
import{_ as i,o as a,c as n,a2 as t}from"./chunks/framework.BWuWLRhz.js";const u=JSON.parse('{"title":"Architecture Migration Decisions","description":"","frontmatter":{},"headers":[],"relativePath":"architecture/migration-decisions.md","filePath":"architecture/migration-decisions.md","lastUpdated":null}'),o={name:"architecture/migration-decisions.md"};function s(r,e,l,c,d,p){return a(),n("div",null,[...e[0]||(e[0]=[t("",55)])])}const h=i(o,[["render",s]]);export{u as __pageData,h as default};
@@ -1,30 +0,0 @@
import{_ as n,o as e,c as s,a2 as i}from"./chunks/framework.BWuWLRhz.js";const m=JSON.parse('{"title":"Repository Organisation","description":"","frontmatter":{},"headers":[],"relativePath":"architecture/organisation.md","filePath":"architecture/organisation.md","lastUpdated":null}'),t={name:"architecture/organisation.md"};function o(p,a,r,l,c,d){return e(),s("div",null,[...a[0]||(a[0]=[i(`<h1 id="repository-organisation" tabindex="-1">Repository Organisation <a class="header-anchor" href="#repository-organisation" aria-label="Permalink to &quot;Repository Organisation&quot;">​</a></h1><p><strong>Status:</strong> Approved<br><strong>Date:</strong> 2026-07-28<br><strong>Beads issue:</strong> <code>archie-core-5d7</code></p><h2 id="target-structure" tabindex="-1">Target structure <a class="header-anchor" href="#target-structure" aria-label="Permalink to &quot;Target structure&quot;">​</a></h2><p>Archie MUST be organised around cohesive application responsibilities:</p><div class="language-tree vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">tree</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>cmd/</span></span>
<span class="line"><span> archied/</span></span>
<span class="line"><span> archie-agent/</span></span>
<span class="line"><span></span></span>
<span class="line"><span>internal/</span></span>
<span class="line"><span> domain/</span></span>
<span class="line"><span> &lt;area&gt;/</span></span>
<span class="line"><span> eventbus/</span></span>
<span class="line"><span> policy/</span></span>
<span class="line"><span> infrastructure/</span></span>
<span class="line"><span> configuration/</span></span>
<span class="line"><span> eventbus/</span></span>
<span class="line"><span> nats/</span></span>
<span class="line"><span> forge/</span></span>
<span class="line"><span> persistence/</span></span>
<span class="line"><span> &lt;external-service&gt;/</span></span>
<span class="line"><span> app/</span></span>
<span class="line"><span> archied/</span></span>
<span class="line"><span> agentworker/</span></span>
<span class="line"><span></span></span>
<span class="line"><span>plugins/</span></span>
<span class="line"><span> &lt;plugin&gt;/</span></span>
<span class="line"><span>deployments/</span></span>
<span class="line"><span> &lt;supported-assembly&gt;/</span></span>
<span class="line"><span>docs/</span></span>
<span class="line"><span> guides/</span></span>
<span class="line"><span>examples/</span></span>
<span class="line"><span> &lt;copyable-example&gt;/</span></span>
<span class="line"><span>extras/</span></span>
<span class="line"><span> &lt;optional-extension&gt;/</span></span></code></pre></div><p>Domain names are chosen from application behaviour during package review. Existing names MUST NOT be retained merely to reduce migration work.</p><h2 id="domain-areas" tabindex="-1">Domain areas <a class="header-anchor" href="#domain-areas" aria-label="Permalink to &quot;Domain areas&quot;">​</a></h2><p>A domain owns one cohesive job performed by Archie. It contains that job&#39;s language, state, rules, operations, commands, events, policy implementations, runtime settings, and required service contracts.</p><p>Code that changes together SHOULD live together. Empty or ceremonial <code>entities</code>, <code>repositories</code>, or <code>services</code> layers are prohibited.</p><h2 id="application-composition" tabindex="-1">Application composition <a class="header-anchor" href="#application-composition" aria-label="Permalink to &quot;Application composition&quot;">​</a></h2><p><code>internal/app</code>:</p><ul><li>constructs domains and infrastructure implementations;</li><li>translates external configuration into domain and plugin settings;</li><li>connects commands, events, and shared contracts;</li><li>starts services in dependency order;</li><li>owns health aggregation and shutdown ordering.</li></ul><p><code>cmd/*</code> parses only process-level input and invokes the relevant application composition package. It MUST NOT contain substantive wiring or act as a service locator.</p><h2 id="process-boundaries" tabindex="-1">Process boundaries <a class="header-anchor" href="#process-boundaries" aria-label="Permalink to &quot;Process boundaries&quot;">​</a></h2><p>Archie begins as a modular monolith even when capabilities run in separate processes. A domain becomes a separately deployed service only for a concrete need such as security isolation, independent scaling, failure containment, or independent operation.</p><p>Possible future extraction does not justify premature network protocols or duplicated service scaffolding.</p><h2 id="optional-and-operational-material" tabindex="-1">Optional and operational material <a class="header-anchor" href="#optional-and-operational-material" aria-label="Permalink to &quot;Optional and operational material&quot;">​</a></h2><ul><li><code>extras/&lt;extension&gt;</code> contains a maintained optional extension with real behaviour. Core Archie MUST NOT import it, and removing <code>extras/</code> MUST NOT prevent the core application from building or running.</li><li><code>deployments/&lt;assembly&gt;</code> contains a supported assembly, including deployment definitions and concise operational instructions.</li><li><code>docs/guides/</code> contains handwritten explanation and links to generated reference material.</li><li><code>examples/</code> contains copyable samples with explicit purpose, prerequisites, and support expectations.</li></ul><p>Supported assemblies SHOULD demonstrate that capabilities can be selected independently.</p>`,19)])])}const h=n(t,[["render",o]]);export{m as __pageData,h as default};
@@ -1 +0,0 @@
import{_ as n,o as e,c as s,a2 as i}from"./chunks/framework.BWuWLRhz.js";const m=JSON.parse('{"title":"Repository Organisation","description":"","frontmatter":{},"headers":[],"relativePath":"architecture/organisation.md","filePath":"architecture/organisation.md","lastUpdated":null}'),t={name:"architecture/organisation.md"};function o(p,a,r,l,c,d){return e(),s("div",null,[...a[0]||(a[0]=[i("",19)])])}const h=n(t,[["render",o]]);export{m as __pageData,h as default};
@@ -1 +0,0 @@
import{_ as t,o as r,c as a,a2 as i}from"./chunks/framework.BWuWLRhz.js";const p=JSON.parse('{"title":"Domain and Feature Review Procedure","description":"","frontmatter":{},"headers":[],"relativePath":"architecture/package-review.md","filePath":"architecture/package-review.md","lastUpdated":null}'),n={name:"architecture/package-review.md"};function o(d,e,s,c,l,u){return r(),a("div",null,[...e[0]||(e[0]=[i('<h1 id="domain-and-feature-review-procedure" tabindex="-1">Domain and Feature Review Procedure <a class="header-anchor" href="#domain-and-feature-review-procedure" aria-label="Permalink to &quot;Domain and Feature Review Procedure&quot;">​</a></h1><p><strong>Status:</strong> Active<br><strong>Date:</strong> 2026-07-28<br><strong>Beads issue:</strong> <code>archie-core-5d7</code></p><h2 id="purpose" tabindex="-1">Purpose <a class="header-anchor" href="#purpose" aria-label="Permalink to &quot;Purpose&quot;">​</a></h2><p>Architecture work proceeds one domain or feature at a time. Before any design question, the selected area is researched across its complete live implementation, consumers, tests, state, configuration, and runtime wiring.</p><p>Existing packages are evidence, not the unit that drives the interview. Placement follows behaviour and ownership, not the existing directory name.</p><p>No restructuring implementation begins until the relevant package decisions are agreed and recorded in the focused domain or requirement document.</p><h2 id="required-research" tabindex="-1">Required research <a class="header-anchor" href="#required-research" aria-label="Permalink to &quot;Required research&quot;">​</a></h2><p>Before design questions, the current-state report MUST identify:</p><ul><li>entry points and runtime composition;</li><li>state, persistence, and lifecycle;</li><li>public and internal contracts;</li><li>commands, events, and policy enforcement;</li><li>configuration and defaults;</li><li>all consumers and cross-domain interactions;</li><li>process and infrastructure boundaries;</li><li>tests, failure behaviour, and known invariants;</li><li>duplicated or conflicting implementations;</li><li>documentation that disagrees with live code.</li></ul><p>Discoverable facts MUST be investigated rather than presented to the user as design questions.</p><h2 id="required-decisions" tabindex="-1">Required decisions <a class="header-anchor" href="#required-decisions" aria-label="Permalink to &quot;Required decisions&quot;">​</a></h2><p>Each package review records:</p><table tabindex="0"><thead><tr><th>Decision</th><th>Required result</th></tr></thead><tbody><tr><td>Owned behaviour</td><td>The cohesive job the code performs</td></tr><tr><td>Domain ownership</td><td>The owner of the behaviour and vocabulary</td></tr><tr><td>Final location</td><td>Its target path</td></tr><tr><td>Public contracts</td><td>The smallest interfaces, commands, and events exposed</td></tr><tr><td>Required services</td><td>Domain-defined interfaces implemented by infrastructure</td></tr><tr><td>State ownership</td><td>The owner of each mutable record and transition</td></tr><tr><td>Dependencies</td><td>Allowed imports and dependencies to remove</td></tr><tr><td>Duplication</td><td>Code to consolidate, delete, or keep separate</td></tr><tr><td>Plugin status</td><td>Core domain, shared contract, infrastructure, plugin, or extra</td></tr><tr><td>Process boundary</td><td>In-process, or the concrete reason for isolation</td></tr><tr><td>Configuration</td><td>Settings owned by the domain or plugin</td></tr><tr><td>Policy</td><td>Definitions, evaluators, consequences, and shared mechanics used</td></tr><tr><td>Documentation</td><td>Authoritative definitions and generated reference</td></tr><tr><td>Migration constraints</td><td>Behaviour and data that must remain correct</td></tr></tbody></table><h2 id="interview-method" tabindex="-1">Interview method <a class="header-anchor" href="#interview-method" aria-label="Permalink to &quot;Interview method&quot;">​</a></h2><p>For every selected domain or feature:</p><ol><li>Declare the single area under review.</li><li>Complete the current-state research.</li><li>Explain actual behaviour in plain technical language.</li><li>Separate facts from design decisions and concerns.</li><li>Resolve obvious consequences directly and ask only questions whose answer materially changes behaviour or structure.</li><li>Record each confirmed decision in its focused document.</li><li>Complete that area&#39;s handoff before selecting another.</li><li>Keep unrelated domains outside the implementation scope.</li></ol>',16)])])}const m=t(n,[["render",o]]);export{p as __pageData,m as default};
@@ -1 +0,0 @@
import{_ as t,o as r,c as a,a2 as i}from"./chunks/framework.BWuWLRhz.js";const p=JSON.parse('{"title":"Domain and Feature Review Procedure","description":"","frontmatter":{},"headers":[],"relativePath":"architecture/package-review.md","filePath":"architecture/package-review.md","lastUpdated":null}'),n={name:"architecture/package-review.md"};function o(d,e,s,c,l,u){return r(),a("div",null,[...e[0]||(e[0]=[i("",16)])])}const m=t(n,[["render",o]]);export{p as __pageData,m as default};
@@ -1 +0,0 @@
import{_ as i,o as n,c as t,a2 as a}from"./chunks/framework.BWuWLRhz.js";const m=JSON.parse('{"title":"Plugins and Extensions","description":"","frontmatter":{},"headers":[],"relativePath":"architecture/plugins-and-extensions.md","filePath":"architecture/plugins-and-extensions.md","lastUpdated":null}'),o={name:"architecture/plugins-and-extensions.md"};function r(l,e,s,c,d,p){return n(),t("div",null,[...e[0]||(e[0]=[a('<h1 id="plugins-and-extensions" tabindex="-1">Plugins and Extensions <a class="header-anchor" href="#plugins-and-extensions" aria-label="Permalink to &quot;Plugins and Extensions&quot;">​</a></h1><p><strong>Status:</strong> Approved foundation<br><strong>Date:</strong> 2026-07-28<br><strong>Beads issue:</strong> <code>archie-core-5d7</code></p><h2 id="plugin-framework" tabindex="-1">Plugin framework <a class="header-anchor" href="#plugin-framework" aria-label="Permalink to &quot;Plugin framework&quot;">​</a></h2><p>The core plugin domain lives under <code>internal/domain/plugin</code>. It owns:</p><ul><li>plugin identity and metadata;</li><li>discovery and registration contracts;</li><li>lifecycle rules;</li><li>capability registration;</li><li>validation and compatibility rules.</li></ul><p>The generic plugin contract remains metadata-only. Functionality is exposed through narrow typed capability contracts with an owning registry or manager.</p><p>Workflow plugins belong to the Workflow capability family. The Workflow domain at <code>internal/domain/workflow</code> owns their typed registration, validation, versioning, definition, and execution contracts. The generic plugin domain may provide plugin identity, discovery, compatibility, and lifecycle mechanics, but it MUST NOT define Workflow semantics or expose untyped Workflow hooks.</p><h2 id="plugin-implementations" tabindex="-1">Plugin implementations <a class="header-anchor" href="#plugin-implementations" aria-label="Permalink to &quot;Plugin implementations&quot;">​</a></h2><p>First-party plugins are self-contained vertical modules under <code>plugins/&lt;plugin&gt;</code>.</p><p>A plugin:</p><ul><li>owns its implementation, settings, templates, assets, and tests;</li><li>receives only explicitly supplied contracts and services;</li><li>MUST NOT receive daemon internals, a service locator, or unrestricted application access;</li><li>MUST NOT import arbitrary infrastructure or application composition code;</li><li>MAY use approved domain and shared application contracts;</li><li>MUST remain removable without changes to unrelated domains.</li></ul><p>Plugins may be internally cohesive like small services. They do not become network services without a concrete security or operational reason.</p>',12)])])}const g=i(o,[["render",r]]);export{m as __pageData,g as default};
@@ -1 +0,0 @@
import{_ as i,o as n,c as t,a2 as a}from"./chunks/framework.BWuWLRhz.js";const m=JSON.parse('{"title":"Plugins and Extensions","description":"","frontmatter":{},"headers":[],"relativePath":"architecture/plugins-and-extensions.md","filePath":"architecture/plugins-and-extensions.md","lastUpdated":null}'),o={name:"architecture/plugins-and-extensions.md"};function r(l,e,s,c,d,p){return n(),t("div",null,[...e[0]||(e[0]=[a("",12)])])}const g=i(o,[["render",r]]);export{m as __pageData,g as default};
@@ -1 +0,0 @@
import{_ as i,o as t,c as a,a2 as o}from"./chunks/framework.BWuWLRhz.js";const h=JSON.parse('{"title":"Policy System","description":"","frontmatter":{},"headers":[],"relativePath":"architecture/policy.md","filePath":"architecture/policy.md","lastUpdated":null}'),n={name:"architecture/policy.md"};function s(r,e,c,l,d,p){return t(),a("div",null,[...e[0]||(e[0]=[o('<h1 id="policy-system" tabindex="-1">Policy System <a class="header-anchor" href="#policy-system" aria-label="Permalink to &quot;Policy System&quot;">​</a></h1><p><strong>Status:</strong> Approved foundation; exact API is deferred<br><strong>Date:</strong> 2026-07-28<br><strong>Beads issue:</strong> <code>archie-core-5d7</code></p><h2 id="purpose" tabindex="-1">Purpose <a class="header-anchor" href="#purpose" aria-label="Permalink to &quot;Purpose&quot;">​</a></h2><p>Retry limits, authorization, gates, commands, protected paths, tool availability, and similar rules define or constrain what Archie may do. They need consistent consumption, composition, evidence, and audit without erasing their different domain meanings.</p><h2 id="ownership" tabindex="-1">Ownership <a class="header-anchor" href="#ownership" aria-label="Permalink to &quot;Ownership&quot;">​</a></h2><p><code>internal/policy</code> is an explicitly approved shared application contract. It is not infrastructure and it is not a generic domain that owns every rule.</p><p>The shared policy system owns:</p><ul><li>policy identity, version, scope, and applicability;</li><li>typed evaluation invocation;</li><li>deterministic composition and precedence;</li><li>common evaluation states such as satisfied, violated, indeterminate, and not applicable;</li><li>reasons and evidence;</li><li>evaluation audit records;</li><li>registration, discovery, and lifecycle.</li></ul><p>Each consuming domain owns:</p><ul><li>its policy vocabulary and typed inputs;</li><li>its concrete policy definitions;</li><li>its evaluators;</li><li>the meaning and consequence of an evaluation.</li></ul><p>Access therefore owns principals, resources, actions, and authorization consequences. Task lifecycle owns retry eligibility and exhaustion. Task execution owns gate requirements. Workspace mutation owns protected-path effects. Tool execution owns tool and command constraints.</p><p>These policies use consistent evaluation mechanics without pretending their decisions are semantically interchangeable.</p><h2 id="infrastructure" tabindex="-1">Infrastructure <a class="header-anchor" href="#infrastructure" aria-label="Permalink to &quot;Infrastructure&quot;">​</a></h2><p>Infrastructure MAY load, persist, distribute, and audit external policy representations. It MUST NOT define what Archie allows or assign the meaning of a domain policy result.</p><p>The exact Go API, composition operators, precedence rules, and representation format require a focused policy design pass.</p>',15)])])}const m=i(n,[["render",s]]);export{h as __pageData,m as default};
@@ -1 +0,0 @@
import{_ as i,o as t,c as a,a2 as o}from"./chunks/framework.BWuWLRhz.js";const h=JSON.parse('{"title":"Policy System","description":"","frontmatter":{},"headers":[],"relativePath":"architecture/policy.md","filePath":"architecture/policy.md","lastUpdated":null}'),n={name:"architecture/policy.md"};function s(r,e,c,l,d,p){return t(),a("div",null,[...e[0]||(e[0]=[o("",15)])])}const m=i(n,[["render",s]]);export{h as __pageData,m as default};
@@ -1 +0,0 @@
import{_ as a,o as t,c as i,a2 as n}from"./chunks/framework.BWuWLRhz.js";const p=JSON.parse('{"title":"Safe Change and Recovery","description":"","frontmatter":{},"headers":[],"relativePath":"architecture/safe-change-and-recovery.md","filePath":"architecture/safe-change-and-recovery.md","lastUpdated":null}'),o={name:"architecture/safe-change-and-recovery.md"};function r(s,e,c,d,l,h){return t(),i("div",null,[...e[0]||(e[0]=[n('<h1 id="safe-change-and-recovery" tabindex="-1">Safe Change and Recovery <a class="header-anchor" href="#safe-change-and-recovery" aria-label="Permalink to &quot;Safe Change and Recovery&quot;">​</a></h1><p><strong>Status:</strong> Requirements approved; mechanics are under design<br><strong>Date:</strong> 2026-07-28<br><strong>Beads issue:</strong> <code>archie-core-5d7</code></p><h2 id="purpose" tabindex="-1">Purpose <a class="header-anchor" href="#purpose" aria-label="Permalink to &quot;Purpose&quot;">​</a></h2><p>Archie is built and improved by agents as well as humans. The architecture MUST make a change easy to locate, understand, test, audit, extend, and reverse without requiring its author to understand unrelated parts of the application.</p><p>Separation of concerns is therefore an operational safety boundary, not only a code-organisation preference.</p><h2 id="required-outcomes" tabindex="-1">Required outcomes <a class="header-anchor" href="#required-outcomes" aria-label="Permalink to &quot;Required outcomes&quot;">​</a></h2><ul><li>An agent can improve a focused feature without receiving authority over unrelated domains.</li><li>Every event, function, action, setting, and policy has an identifiable owner and provenance.</li><li>Source and runtime changes pass deterministic checks outside the actor making the change.</li><li>A rejected or unhealthy candidate cannot replace the last known working version.</li><li>Invalid user configuration does not terminate an otherwise healthy application.</li><li>Configuration and service failures are observable, attributed, and eligible for bounded remediation or rollback.</li><li>The application continues serving unaffected capabilities when one capability is misconfigured or unhealthy.</li><li>Recovery failure is reported and contained rather than hidden in an unbounded retry loop.</li></ul><h2 id="source-changes" tabindex="-1">Source changes <a class="header-anchor" href="#source-changes" aria-label="Permalink to &quot;Source changes&quot;">​</a></h2><p>Agent-authored source changes occur through the task-execution boundary in an isolated workspace. The agent does not directly mutate the running installation.</p><p>Promotion is controlled by deterministic repository-owned policy, including tests, generated-reference drift checks, protected paths, change scope, and other required gates. The actor proposing a change cannot waive these checks.</p><p>Repository and domain separation SHOULD allow a task to load and modify only the governing requirements and code for its declared scope.</p><h2 id="runtime-changes" tabindex="-1">Runtime changes <a class="header-anchor" href="#runtime-changes" aria-label="Permalink to &quot;Runtime changes&quot;">​</a></h2><p>Configuration and other runtime changes are proposed as candidates rather than mutating the active state in place.</p><p>The affected domain owns:</p><ul><li>the command describing the semantic change;</li><li>validation of its typed settings;</li><li>health signals that demonstrate correct operation;</li><li>domain-specific remediation and rollback consequences.</li></ul><p>Shared policy supplies consistent evaluation, evidence, and audit mechanics. Identity supplies actor attribution. Infrastructure supplies external configuration storage, service control, and other operational adapters.</p><h2 id="runtime-change-protocol" tabindex="-1">Runtime change protocol <a class="header-anchor" href="#runtime-change-protocol" aria-label="Permalink to &quot;Runtime change protocol&quot;">​</a></h2><p>Last-known-good preservation and candidate promotion are the universal runtime change protocol.</p><ol><li>An identity proposes an immutable candidate version.</li><li>Infrastructure parses it without changing active state.</li><li>Each affected domain validates its typed settings.</li><li>Shared policy evaluates cross-cutting constraints.</li><li>Each affected capability prepares the candidate without destroying its active instance.</li><li>Capability-specific health checks prove the candidate works.</li><li>Runtime supervision atomically promotes the candidate.</li><li>A bounded observation period watches for delayed failure.</li><li>Failure restores the last-known-good version and records the reason, evidence, actor, and involved versions.</li><li>Repeated remediation failure stops retrying, isolates the capability, and reports the fault.</li></ol><p>The affected domain owns the semantic change command, typed validation, health signals, and remediation consequences. Shared runtime superLine truncated
@@ -1 +0,0 @@
import{_ as a,o as t,c as i,a2 as n}from"./chunks/framework.BWuWLRhz.js";const p=JSON.parse('{"title":"Safe Change and Recovery","description":"","frontmatter":{},"headers":[],"relativePath":"architecture/safe-change-and-recovery.md","filePath":"architecture/safe-change-and-recovery.md","lastUpdated":null}'),o={name:"architecture/safe-change-and-recovery.md"};function r(s,e,c,d,l,h){return t(),i("div",null,[...e[0]||(e[0]=[n("",25)])])}const g=a(o,[["render",r]]);export{p as __pageData,g as default};
@@ -1 +0,0 @@
import{_ as t,o,c as a,a2 as i}from"./chunks/framework.BWuWLRhz.js";const g=JSON.parse('{"title":"archied -- design notes","description":"","frontmatter":{},"headers":[],"relativePath":"archive/DESIGN.md","filePath":"archive/DESIGN.md","lastUpdated":1785228410000}'),n={name:"archive/DESIGN.md"};function r(s,e,l,d,c,p){return o(),a("div",null,[...e[0]||(e[0]=[i('<h1 id="archied-design-notes" tabindex="-1">archied -- design notes <a class="header-anchor" href="#archied-design-notes" aria-label="Permalink to &quot;archied -- design notes&quot;">​</a></h1><p>Archie is a resident daemon that keeps personal projects moving: it polls GitHub for issues labelled <code>archie</code>, works each one in an isolated fresh-clone worktree through a routed <strong>workflow</strong>, and opens a pull request for human review. Sam reviews and merges; the machine grinds in between.</p><p>Guiding principle: <strong>environmental constraints over prompt instructions.</strong> Agents don&#39;t get asked nicely to write good code -- the quality gate (vet/build/test/lint, configurable per repo and per workflow stage) refuses to let a run succeed until it passes. The gate mechanics live in <code>ai-sdk/agentloop</code>; this repo owns orchestration only.</p><h2 id="workflows-not-a-pipeline" tabindex="-1">Workflows, not a pipeline <a class="header-anchor" href="#workflows-not-a-pipeline" aria-label="Permalink to &quot;Workflows, not a pipeline&quot;">​</a></h2><p><code>internal/workflow</code> is the engine: a Workflow is an ordered list of stages over a shared TaskContext; stages are deterministic steps (worktree, gate, diff cap, PR, comments -- the shared step library in <code>steps.go</code>) or agent stages (<code>agentloop.Run</code> with a stage-specific mission/toolset/gate). Routing is label-driven (<code>bug</code> → tdd, <code>feature</code> → feasibility, default → implement), refinable by an LLM triage stage. Adding a workflow must never require touching the engine or reimplementing steps.</p><p>Planned workflows:</p><ul><li><strong>bootstrap</strong> (registered): deterministic marker-file PR proving invites/clone/push/PR plumbing.</li><li><strong>implement</strong>: planner (read-only agentloop, plan posted to the issue) → builder (full toolset, repo gate) → diff cap → PR.</li><li><strong>tdd</strong> (bugfixes): analyse → problem surface → write failing repro tests (gate stage with <code>ExpectFailure</code>) → fix (gate: suite passes) → PR.</li><li><strong>feasibility</strong> (features): read-only analysis → roadmap fit → won&#39;t-do close with reasons, or plan + PRD → email Sam → <code>waiting_human</code> → LLM-judged reply → hand off to implement.</li></ul><h2 id="task-lifecycle" tabindex="-1">Task lifecycle <a class="header-anchor" href="#task-lifecycle" aria-label="Permalink to &quot;Task lifecycle&quot;">​</a></h2><p><code>queued → running(workflow:stage) → waiting_human | pr_open → merged | parked | rejected | closed_wont_do</code></p><p>SQLite (<code>internal/store</code>), WAL, one row per issue with a transitions audit table. Crash recovery: <code>running</code> tasks re-queue on startup with attempt++. Parks are never silent -- every park comments on the issue with the reason and gate output.</p><h2 id="security-posture" tabindex="-1">Security posture <a class="header-anchor" href="#security-posture" aria-label="Permalink to &quot;Security posture&quot;">​</a></h2><ul><li>Fine-grained PAT on the bot account only (Contents RW, PRs RW, Issues RW, Metadata R), via <code>ARCHIE_GITHUB_TOKEN</code>; git auth through an askpass helper so the token stays out of argv and <code>.git/config</code>.</li><li>The model never runs git: <code>internal/worktree</code> owns all repo operations deterministically.</li><li>Agent tools are jailed to the task worktree (toolkit path jail); intended deployment is a dedicated Incus container so the blast radius is environmental, not prompt-negotiated.</li></ul>',12)])])}const h=t(n,[["render",r]]);export{g as __pageData,h as default};
@@ -1 +0,0 @@
import{_ as t,o,c as a,a2 as i}from"./chunks/framework.BWuWLRhz.js";const g=JSON.parse('{"title":"archied -- design notes","description":"","frontmatter":{},"headers":[],"relativePath":"archive/DESIGN.md","filePath":"archive/DESIGN.md","lastUpdated":1785228410000}'),n={name:"archive/DESIGN.md"};function r(s,e,l,d,c,p){return o(),a("div",null,[...e[0]||(e[0]=[i("",12)])])}const h=t(n,[["render",r]]);export{g as __pageData,h as default};
@@ -1,102 +0,0 @@
import{_ as s,o as a,c as i,a2 as t}from"./chunks/framework.BWuWLRhz.js";const g=JSON.parse('{"title":"archie-core v2 Architecture -- Design Document","description":"","frontmatter":{},"headers":[],"relativePath":"archive/archie-core-architecture.md","filePath":"archive/archie-core-architecture.md","lastUpdated":1785228410000}'),n={name:"archive/archie-core-architecture.md"};function o(l,e,r,d,c,p){return a(),i("div",null,[...e[0]||(e[0]=[t(`<h1 id="archie-core-v2-architecture-design-document" tabindex="-1">archie-core v2 Architecture -- Design Document <a class="header-anchor" href="#archie-core-v2-architecture-design-document" aria-label="Permalink to &quot;archie-core v2 Architecture -- Design Document&quot;">​</a></h1><p><strong>Author:</strong> Archie (Hermes agent)<br><strong>Date:</strong> 2026-07-21 (implementation status updated 2026-07-22)<br><strong>Status:</strong> Final (substantially implemented -- remaining aspirational items are pluggable storage backends and Layer 2 daemon plugin loader)</p><hr><h2 id="_0-implementation-status-as-of-2026-07-22-updated-2026-07-22" tabindex="-1">0. Implementation status (as of 2026-07-22, updated 2026-07-22) <a class="header-anchor" href="#_0-implementation-status-as-of-2026-07-22-updated-2026-07-22" aria-label="Permalink to &quot;0. Implementation status (as of 2026-07-22, updated 2026-07-22)&quot;">​</a></h2><p>This document describes a target end state. The table below is the ground truth; read it before treating any section as already built.</p><table tabindex="0"><thead><tr><th>Area</th><th>Status</th><th>What actually exists today (post-e4d11b1)</th></tr></thead><tbody><tr><td>Daemon/agent binary split</td><td><strong>Implemented</strong></td><td><code>cmd/archied</code> and <code>cmd/archie-agent</code> both exist. <code>archie-agent</code> 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 (<code>workflow.Route</code>, <code>workflow.Run</code>) now run inside the agent, not the daemon. Three agent modes: <code>inprocess</code>, <code>subprocess</code>, <code>nats</code>.</td></tr><tr><td>Sandbox / &quot;daemon never runs untrusted code&quot;</td><td><strong>Partial</strong></td><td>Default mode is still <code>inprocess</code> for development. Docker sandbox mode (<code>agent.mode = &quot;nats&quot;</code> + <code>containers.enabled = true</code>) runs each task in an ephemeral Docker container with workspace bind-mounted at <code>/workspace</code>. <code>internal/container/pool.go</code> manages full lifecycle: pull, create, start, release, orphan recovery. Daemon dispatch and container lifecycle both enforce <code>max_concurrency</code>; same-repo tasks remain serialized.</td></tr><tr><td>NATS / JetStream messaging</td><td><strong>Implemented</strong></td><td><code>internal/nats/client.go</code>: JetStream connect, stream creation (WorkQueue retention, file storage), pull consumer (durable, ack-wait 5min, max-deliver 3, dedup by Msg-Id), <code>PublishTask</code>, <code>Fetch</code>, <code>NewReplyInbox</code>, and optional token authentication. Subject hierarchy lives in <code>internal/nats/subjects.go</code>; <code>internal/agentexec/nats.go</code> implements request/reply agent execution.</td></tr><tr><td>Docker container sandbox</td><td><strong>Implemented</strong></td><td><code>internal/container/pool.go</code> (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. <code>Dockerfile</code> at repo root builds archie-agent fat image. <code>[containers]</code> config block: enabled, image, max_concurrency, max_uptime, pull_policy. <code>agent.mode = &quot;nats&quot;</code> required when containers enabled.</td></tr><tr><td><code>/data/</code> volume, <code>task.json</code></td><td><strong>Partial</strong></td><td><code>container.WriteTaskJSON()</code> writes task payload to the worktree before container acquire. The container pool bind-mounts the isolated task worktree at <code>/data/worktree</code>; configured repos also receive a persistent <code>/data/repo</code> Docker volume. Task payload travels over NATS as the primary channel; <code>/data/task.json</code> is a boot-time brief for the container.</td></tr><tr><td><code>[containers]</code> config block</td><td><strong>Implemented</strong></td><td><code>ContainerConfig</code> struct in config.go: enabled, image, max_concurrency, max_uptime, pull_policy. Validated on load.</td></tr><tr><td>Yaegi extensibility (gates, custom stages, skill scripts)</td><td><strong>Implemented</strong></td><td>Three surfaces: <code>.archie/gate.go</code>, <code>.archie/stages/*.go</code>, skill scripts via <code>run_go_script</code> tool. All in-process via Yaegi with generated symbol tables and panic recovery. Full detail in <code>docs/prds/yaegi-plugin-system.md</code>.</td> Line truncated
<span class="line"><span>archie.task.feature -- Feasibility workflow tasks</span></span>
<span class="line"><span>archie.task.default -- Implement workflow tasks</span></span>
<span class="line"><span>archie.task.bootstrap -- Bootstrap diagnostic tasks</span></span></code></pre></div><p>Daemon publishes to the appropriate subject based on label routing. Agents subscribe to subjects they&#39;re configured to handle.</p><h3 id="agent-communication-per-task" tabindex="-1">Agent communication (per-task) <a class="header-anchor" href="#agent-communication-per-task" aria-label="Permalink to &quot;Agent communication (per-task)&quot;">​</a></h3><div class="language-events vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">events</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>archie.agent.&lt;task_id&gt;.response -- Agent output: summaries, PR bodies, results. Daemon reviews before human delivery.</span></span>
<span class="line"><span>archie.agent.&lt;task_id&gt;.system -- Internal comms: log dumps, data requests, health, PII warnings. Never forwarded unprompted.</span></span>
<span class="line"><span>archie.agent.&lt;task_id&gt;.request -- Optional: agent requests additional data from the daemon.</span></span></code></pre></div><p>The daemon gatekeeps the response channel -- no agent output reaches a human without daemon review.</p><h3 id="jetstream-durability" tabindex="-1">JetStream durability <a class="header-anchor" href="#jetstream-durability" aria-label="Permalink to &quot;JetStream durability&quot;">​</a></h3><p>Tasks are published with JetStream persistence. On agent container failure, NATS redelivers. The daemon doesn&#39;t need retry logic -- NATS handles it.</p><hr><h2 id="_3-persistent-volume" tabindex="-1">3. Persistent volume <a class="header-anchor" href="#_3-persistent-volume" aria-label="Permalink to &quot;3. Persistent volume&quot;">​</a></h2><blockquote><p><strong>Status: partially implemented.</strong> <code>task.json</code>, <code>/data/worktree</code>, optional per-repo <code>/data/repo</code> 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. <code>session.jsonl</code>, <code>memory.jsonl</code>, and staged plugin volumes remain unimplemented.</p></blockquote><h3 id="data-layout" tabindex="-1">/data/ layout <a class="header-anchor" href="#data-layout" aria-label="Permalink to &quot;/data/ layout&quot;">​</a></h3><div class="language-tree vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">tree</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>/data/</span></span>
<span class="line"><span>|---- task.json # Full task payload (owner, repo, issue, title, body, labels, workflow)</span></span>
<span class="line"><span>|---- session.jsonl # Agent session transcript (appended per stage)</span></span>
<span class="line"><span>|---- memory.jsonl # Optional: cross-session memory (persisted per project)</span></span>
<span class="line"><span>|---- plugins/ # Bundled plugins from the skill (daemon-staged, overrides worktree)</span></span>
<span class="line"><span>|---- worktree/ # Read-only mount of the cloned repo (managed by daemon)</span></span></code></pre></div><h3 id="task-json" tabindex="-1">task.json <a class="header-anchor" href="#task-json" aria-label="Permalink to &quot;task.json&quot;">​</a></h3><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;id&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">42</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;owner&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;sam&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;repo&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;example-service&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;issue_number&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">170</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;title&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Add /copy command for messages and session transcripts&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;body&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;labels&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;enhancement&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;archie&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;workflow&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;implement&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;branch&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;archie/issue-170&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;plan&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;config&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;base_branch&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;main&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;gate&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;gofumpt&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;-w&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;go&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;vet&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;./...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;go&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;test&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;-race&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;./...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ],</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;protect&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;_templ.go&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;ecosystem&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;go&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;test_glob&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;*_test.go&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;nats&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;url&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;nats://archie-core:4222&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;response_subject&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;archie.agent.42.response&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;system_subject&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;archie.agent.42.system&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;request_subject&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;archie.agent.42.request&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>The daemon writes <code>task.json</code> to the volume before the container starts. The agent reads it on boot.</p><h3 id="volume-lifecycle" tabindex="-1">Volume lifecycle <a class="header-anchor" href="#volume-lifecycle" aria-label="Permalink to &quot;Volume lifecycle&quot;">​</a></h3><ul><li>Created on task start (persistent per-repo if configured)</li><li>Kept until terminal outcome (<code>pr_open</code>, <code>merged</code>, <code>rejected</code>, <code>closed_wont_do</code>) OR TTL expiry</li><li>Parked tasks keep their volume for inspection and requeue reuse</li><li>Cleanup is a daemon responsibility</li></ul><hr><h2 id="_4-container-management" tabindex="-1">4. Container management <a class="header-anchor" href="#_4-container-management" aria-label="Permalink to &quot;4. Container management&quot;">​</a></h2><blockquote><p><strong>Status: implemented with a flatter schema than the sketch below.</strong> <code>[containers]</code> configures the image, concurrency, uptime, pull policy, and persistent-storage TTL. <code>Repo.PersistentStorage</code> opts a repository into the per-repo Docker volume and Git object cache. The backend abstraction exists in <code>internal/storage</code>; additional storage types and structured per-backend configuration remain future work.</p></blockquote><h3 id="daemon-config" tabindex="-1">Daemon config <a class="header-anchor" href="#daemon-config" aria-label="Permalink to &quot;Daemon config&quot;">​</a></h3><div class="language-toml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">toml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Container lifecycle</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">containers</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">max_concurrency = </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">4</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # max simultaneous agent containers</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">max_uptime = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;30m&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # grace period after task completion before kill</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">volume_ttl = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;72h&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # max volume age before cleanup (overrides terminal wait)</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Image strategy</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">containers</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">image</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">registry = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;ghcr.io/sam/archie-agent:latest&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # primary: pull from registry</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">registry_pull = </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # allow pulls</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">dockerfile = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;./Dockerfile.agent&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # fallback: build locally</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">dockerfile_build = </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # allow builds</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Persistent storage</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">containers</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">persistent_storage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">type = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;docker&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # docker (volume), bind, s3, sftp, nfs</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">path = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;archie-data&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # volume name or mount path</span></span></code></pre></div><h3 id="per-repo-persistent-storage-override" tabindex="-1">Per-repo persistent storage override <a class="header-anchor" href="#per-repo-persistent-storage-override" aria-label="Permalink to &quot;Per-repo persistent storage override&quot;">​</a></h3><div class="language-toml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">toml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[[</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">repos</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">owner = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;sam&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">name = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;example-service&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">persistent_storage = { type = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;bind&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, path = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;./archie-core-data/projects/example-service&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span></code></pre></div><p>When configured, each task for this repo mounts the same bind path. Memory persists across sessions. The agent writes to <code>MEMORY.md</code> in this directory.</p><h3 id="agent-image" tabindex="-1">Agent image <a class="header-anchor" href="#agent-image" aria-label="Permalink to &quot;Agent image&quot;">​</a></h3><p>A fat Docker image containing:</p><ul><li>archie-agent binary</li><li>NATS client library</li><li>LLM provider SDKs (ai-sdk runtime)</li><li>Base tools: git, gh, go, golangci-lint, gofumpt, node, python, ruff, pytest, etc.</li><li>esbuild (for TypeScript plugin transpilation)</li><li>Yaegi interpreter (bundled in the binary)</li></ul><p>Pre-built and published to a registry. The daemon pulls on startup. Users can provide their own image via config.</p><hr><h2 id="_5-extensibility-layers" tabindex="-1">5. Extensibility layers <a class="header-anchor" href="#_5-extensibility-layers" aria-label="Permalink to &quot;5. Extensibility layers&quot;">​</a></h2><blockquote><p><strong>Reconciliation note.</strong> 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 <em>does</em> exist -- and is implemented, tested, and already in production -- is described in the sibling PRD <code>docs/prds/yaegi-plugin-system.md</code>, whose three phases (custom gate functions, custom workflow stages, skill scripts) are marked &quot;implemented&quot; and match disk state exactly as of commit <code>d45f21d</code>. That implementation is narrower and shaped differently than what follows:</p><ul><li>It has <strong>no skill-bundling concept</strong> -- <code>.archie/gate.go</code> and <code>.archie/stages/*.go</code> are repo-level, not shipped inside a skill&#39;s <code>plugins/</code> directory; skill scripts (<code>.archie/skills/&lt;skill&gt;/scripts/*.go</code>) are the closest analog but none of the five current skills ship a <code>scripts/</code> directory yet.</li><li>It has <strong>no daemon-side core plugin registry</strong> -- no <code>Plugin</code> interface, no <code>Register(daemon *Daemon)</code>, no <code>~/.config/archie/plugins/</code> loader. Yaegi today only interprets small, narrowly-scoped <code>.go</code> files (gates, stages, scripts) in-process inside <code>archied</code>, using generated symbol tables (<code>internal/gate/gateextract</code>, <code>internal/workflow/wfextract</code>) rather than a general extension-registration interface.</li><li>Custom stages are <strong>auto-discovered and run in filename order</strong>, not routed by name from <code>config.toml</code> -- the workflow engine has no data-driven stage graph today, so the <code>[[workflows.stages]]</code> config sketch below does not correspond to real config.</li></ul><p>Before implementation begins, decide: does Layer 1/Layer 2 as described below <em>replace</em> the existing three Yaegi surfaces, or does it <em>extend</em> them (e.g., teach the existing loaders to also read from a skill&#39;s <code>plugins/</code> directory, and add a genuinely new daemon-side <code>Plugin</code> 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.</p></blockquote><h3 id="layer-1-skills-archie-wf" tabindex="-1">Layer 1: Skills (<code>archie-wf-*</code>) <a class="header-anchor" href="#layer-1-skills-archie-wf" aria-label="Permalink to &quot;Layer 1: Skills (\`archie-wf-*\`)&quot;">​</a></h3><blockquote><p><strong>Status: cosmetic only.</strong> Five <code>SKILL.md</code> files exist today (<code>ecosystem-node</code>, <code>ecosystem-python</code>, <code>go-quality-gate</code>, <code>security-audit</code>, <code>tdd-bugfix</code>) at <code>.archie/skills/&lt;name&gt;/SKILL.md</code> -- a single flat repo-relative location, no worktree-vs-user-level split, no <code>archie-wf-*</code> naming. Each has a <code>metadata.archie</code> block with only <code>tools</code> and <code>engine</code> keys (no <code>plugins</code>, no <code>budget_usd</code>). <strong>No Go code parses SKILL.md frontmatter, discovers skills, or does progressive disclosure</strong> -- grepping for a skill loader, catalog, or frontmatter parser across the repo returns nothing. The workflow <code>Mission</code> strings that drive agent behavior today are hand-written Go string literals in <code>internal/workflow/{impLine truncated
<span class="line"><span>.agents/skills/archie-wf-implement/SKILL.md</span></span>
<span class="line"><span>.agents/skills/archie-wf-feasibility/SKILL.md</span></span>
<span class="line"><span>~/.archie/skills/archie-wf-default/SKILL.md (user-level -- fallback)</span></span></code></pre></div><p>The agent discovers skills at workflow start. The skill matching the task&#39;s workflow type is loaded first. If absent, falls back to <code>archie-wf-default</code>. If that&#39;s absent too, the agent works from AGENTS.md conventions and best practices.</p><h4 id="extended-agentskills-io-format" tabindex="-1">Extended agentskills.io format <a class="header-anchor" href="#extended-agentskills-io-format" aria-label="Permalink to &quot;Extended agentskills.io format&quot;">​</a></h4><p>Skills follow the standard spec (<code>name</code>, <code>description</code>, <code>version</code>, <code>SKILL.md</code> body) with archie-specific metadata:</p><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">---</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">archie-wf-tdd</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> Test-driven bugfix workflow for archie-core. Reproduce the bug with failing tests, prove the repro, fix the code</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> without touching tests.</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">version</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1.0.0</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">metadata</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> archie</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> plugins</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># bundled Yaegi plugins shipped with this skill</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">plugins/custom-gate.go</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # repo-specific gate logic</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">plugins/gosec-check.go</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # security scanner integration</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> tools</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">golangci-lint</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">gofumpt</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">task</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> engine</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">any</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> budget_usd</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">2.00</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">---</span></span></code></pre></div><h4 id="progressive-disclosure" tabindex="-1">Progressive disclosure <a class="header-anchor" href="#progressive-disclosure" aria-label="Permalink to &quot;Progressive disclosure&quot;">​</a></h4><p>Per the agentskills.io spec:</p><ol><li><strong>Catalog</strong> (~100 tokens): <code>name</code> + <code>description</code> loaded at workflow start</li><li><strong>Instructions</strong> (&lt;5000 tokens): Full <code>SKILL.md</code> body when the skill is activated</li><li><strong>Resources</strong> (as needed): References, scripts, and bundled plugins loaded on demand</li></ol><h4 id="bundled-plugins" tabindex="-1">Bundled plugins <a class="header-anchor" href="#bundled-plugins" aria-label="Permalink to &quot;Bundled plugins&quot;">​</a></h4><p>A skill&#39;s <code>plugins/</code> directory contains Yaegi <code>.go</code> files. These are loaded by the agent at workflow start alongside the skill instructions. The daemon copies them to <code>/data/plugins/</code> before the container starts.</p><p>If <code>/data/plugins/</code> already has a plugin with the same name (from persistent project storage), the volume version wins. Conflicts are logged by the daemon.</p><h3 id="layer-2-core-plugins" tabindex="-1">Layer 2: Core plugins <a class="header-anchor" href="#layer-2-core-plugins" aria-label="Permalink to &quot;Layer 2: Core plugins&quot;">​</a></h3><blockquote><p><strong>Status: aspirational, zero code.</strong> No <code>Plugin</code> interface, no plugin registry, no <code>~/.config/archie/plugins/</code> loader exists anywhere in the repo (confirmed by grep for <code>Plugin</code>, plugin registry, and <code>Register(daemon</code> -- zero matches). Yaegi is a real dependency (<code>traefik/yaegi v0.16.1</code>) and is genuinely wired up, but only for the three narrow surfaces in sec.5&#39;s reconciliation note above, all interpreted in-process inside <code>archied</code> -- not for extending the daemon with new forge/ticketing/storage/secrets/notify implementations as described below.</p></blockquote><p>Core plugins live at <code>~/.config/archie/plugins/</code> and extend the daemon itself:</p><div class="language-tree vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">tree</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>~/.config/archie/plugins/</span></span>
<span class="line"><span>|---- forge-gitea.go # Gitea forge implementation</span></span>
<span class="line"><span>|---- forge-gitlab.go # GitLab forge implementation</span></span>
<span class="line"><span>|---- ticketing-jira.go # Jira ticketing integration</span></span>
<span class="line"><span>|---- ticketing-linear.go # Linear ticketing integration</span></span>
<span class="line"><span>|---- storage-s3.go # S3 persistent storage backend</span></span>
<span class="line"><span>|---- vault-secrets.go # HashiCorp Vault integration</span></span>
<span class="line"><span>|---- notify-servicenow.go # ServiceNow integration</span></span></code></pre></div><h4 id="loading" tabindex="-1">Loading <a class="header-anchor" href="#loading" aria-label="Permalink to &quot;Loading&quot;">​</a></h4><p>Loaded by the daemon at startup via Yaegi. Each plugin registers itself with the daemon&#39;s extension registry:</p><div class="language-go vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">go</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Plugin interface (Go, interpreted via Yaegi)</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">type</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Plugin</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> interface</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Version</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Register</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">daemon</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> *</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Daemon</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">error</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>The daemon discovers <code>.go</code> files, evaluates them, extracts the plugin symbol, and calls <code>Register()</code>. Failed plugins are logged and skipped -- the daemon starts with remaining plugins.</p><h4 id="what-core-plugins-can-do" tabindex="-1">What core plugins can do <a class="header-anchor" href="#what-core-plugins-can-do" aria-label="Permalink to &quot;What core plugins can do&quot;">​</a></h4><ul><li><strong>Forges</strong> -- implement the <code>forge.Forge</code> interface. Register themselves as available forge types.</li><li><strong>Ticketing</strong> -- implement a ticketing interface. Poll external systems, format issues into the standard <code>forge.Issue</code> struct.</li><li><strong>Storage backends</strong> -- implement a storage interface. Provide volume population and cleanup.</li><li><strong>Secrets</strong> -- implement a vault interface. Inject credentials into <code>/data/secrets/</code> before agent start.</li><li><strong>Notifications</strong> -- implement a notify interface. Deliver PRDs, status updates beyond the built-in webhook.</li></ul><hr><h2 id="_6-task-lifecycle-v2" tabindex="-1">6. Task lifecycle (v2) <a class="header-anchor" href="#_6-task-lifecycle-v2" aria-label="Permalink to &quot;6. Task lifecycle (v2)&quot;">​</a></h2><blockquote><p><strong>Status: implemented.</strong> NATS JetStream is now the task distribution path (<code>internal/nats/client.go</code>, <code>internal/daemon/daemon.go:drainNATS()</code>). Docker containers spawn per task (<code>internal/container/pool.go</code>). The flow below matches the running code post-e4d11b1.</p></blockquote><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>Discover -&gt; Publish to JetStream -&gt; Agent consumes -&gt; running(workflow:stage)</span></span>
<span class="line"><span> v</span></span>
<span class="line"><span> pr_open -&gt; merged | rejected</span></span>
<span class="line"><span> v</span></span>
<span class="line"><span> waiting_human -&gt; (approved) -&gt; requeue</span></span>
<span class="line"><span> v</span></span>
<span class="line"><span> parked</span></span></code></pre></div><h3 id="detailed-flow" tabindex="-1">Detailed flow <a class="header-anchor" href="#detailed-flow" aria-label="Permalink to &quot;Detailed flow&quot;">​</a></h3><ol><li><strong>Discover</strong> -- daemon polls forges for labelled/assigned issues</li><li><strong>Publish</strong> -- daemon publishes task to <code>archie.task.&lt;workflow_type&gt;</code> JetStream subject</li><li><strong>Spawn</strong> -- daemon creates task volume, writes <code>task.json</code>, stages bundled plugins</li><li><strong>Start container</strong> -- <code>docker run</code> with volume mounts, network (NATS), resource limits</li><li><strong>Agent boots</strong> -- reads <code>task.json</code> from <code>/data/</code>, connects to NATS, discovers skills, loads bundled plugins</li><li><strong>Run workflow</strong> -- agent executes routed workflow stages. Reports progress to system channel. Result to response channel.</li><li><strong>Daemon reviews</strong> -- reads agent response. Forwards to human channels (issue comment, label update, PR). System messages stay internal.</li><li><strong>Grace period</strong> -- agent stays alive for <code>max_uptime</code>. Handles follow-ups (gate re-runs, human replies forwarded by daemon).</li><li><strong>Kill</strong> -- daemon kills container. Volume cleaned up on terminal outcome or TTL expiry.</li></ol><hr><h2 id="_7-agent-daemon-human-flow" tabindex="-1">7. Agent -&gt; daemon -&gt; human flow <a class="header-anchor" href="#_7-agent-daemon-human-flow" aria-label="Permalink to &quot;7. Agent -&gt; daemon -&gt; human flow&quot;">​</a></h2><div class="language-flow vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">flow</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>,---------, response ,---------, reviewed ,----------,</span></span>
<span class="line"><span>| Agent |------------ -&gt; | Daemon |------------ -&gt; | Human |</span></span>
<span class="line"><span>| | system | | queried | channels |</span></span>
<span class="line"><span>| |------------ -&gt; | |&lt;-------------| |</span></span>
<span class="line"><span>|------------ |------------ |-------------</span></span>
<span class="line"><span> |</span></span>
<span class="line"><span> |---- Issue comments (parked, PR, waiting)</span></span>
<span class="line"><span> |---- Label updates (archie:queued -&gt; archie:working -&gt; archie:pr)</span></span>
<span class="line"><span> |---- Notify webhook (feasibility PRD delivered)</span></span>
<span class="line"><span> |---- SSE dashboard (real-time observability)</span></span></code></pre></div><p>The agent writes whatever it wants to <code>response</code>. The daemon reviews it. No agent output reaches a human unprompted. The <code>system</code> channel is purely internal -- the daemon reads it for observability and debugging, never forwards it.</p><hr><h2 id="_8-implementation-phases" tabindex="-1">8. Implementation phases <a class="header-anchor" href="#_8-implementation-phases" aria-label="Permalink to &quot;8. Implementation phases&quot;">​</a></h2><blockquote><p>Updated 2026-07-24 against actual repo state (see sec.0). Items marked <strong>done</strong> 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.</p></blockquote><h3 id="phase-1-binary-split-nats" tabindex="-1">Phase 1: Binary split + NATS <a class="header-anchor" href="#phase-1-binary-split-nats" aria-label="Permalink to &quot;Phase 1: Binary split + NATS&quot;">​</a></h3><ul><li><s>Split <code>archied</code> into daemon binary</s> -- <strong>done</strong>, <code>cmd/archied</code> exists</li><li><s>Create <code>archie-agent</code> binary</s> -- <strong>done, but partial</strong>: <code>cmd/archie-agent</code> exists and executes one workflow <em>stage</em> per invocation over a versioned stdin/stdout JSON protocol (<code>internal/agentexec</code>, protocol v1). Still needed: promote it from a single-stage subprocess worker to the PRD&#39;s per-task process, and move workflow routing/sequencing (<code>workflow.Route</code>/<code>workflow.Run</code>) out of <code>archied</code> and into it.</li><li><s>Add NATS to both (JetStream for task queue, request-reply for comms)</s> -- <strong>done</strong>. <code>[nats]</code> is optional, supports anonymous local mode and token authentication via <code>token_env</code>, and leaves <code>internal/events.Bus</code> as the local observability fan-out.</li><li><s>Daemon publishes, agent consumes, results return via NATS</s> -- <strong>done</strong>. Task discovery uses JetStream work-queue subjects; autonomous stages use JetStream requests plus core NATS reply inboxes.</li><li>Current single-process mode preserved for development (<code>--local</code> flag) -- effectively already true: <code>inprocess</code><code>[agent] mode</code> is the <em>default</em>, not an opt-in fallback, so this constraint is satisfied but should be revisited once subprocess/container modes are the default.</li></ul><h3 id="phase-2-docker-sandbox" tabindex="-1">Phase 2: Docker sandbox <a class="header-anchor" href="#phase-2-docker-sandbox" aria-label="Permalink to &quot;Phase 2: Docker sandbox&quot;">​</a></h3><ul><li>Docker agent image (fat, with tools) -- not started</li><li>Daemon container lifecycle: spawn, volume create, env inject, kill -- not started</li><li><s>Persistent volumes with TTL</s> -- <strong>done</strong>: configured repos receive a persistent Docker volume plus a per-repo Git object cache; both are automatically reaped using <code>containers.volume_ttl</code>.</li><li><s><code>max_concurrency</code> enforcement</s> -- <strong>done</strong>: SQLite and NATS drains dispatch different repositories concurrently up to <code>[containers].max_concurrency</code>; same-repo tasks remain serialized by default.</li><li>Grace period <code>max_uptime</code> -- not started</li><li><strong>Groundwork already in place:</strong> <code>agentexec.Runner</code> (<code>InProcessRunner</code>/<code>SubprocessRunner</code>) is an interface designed, per its own doc comments, to be swapped for a container-backed runner without touching workflow orchestration -- implement <code>ContainerRunner</code> against this interface rather than redesigning the execution boundary.</li></ul><h3 id="phase-3-skills-bundled-plugins" tabindex="-1">Phase 3: Skills + bundled plugins <a class="header-anchor" href="#phase-3-skills-bundled-plugins" aria-label="Permalink to &quot;Phase 3: Skills + bundled plugins&quot;">​</a></h3><ul><li>agentskills.io spec implementation (progressive disclosure) -- not started; current SKILL.md files are unparsed documentation (see sec.5)</li><li><code>archie-wf-*</code> skill discovery from worktree and user paths -- not started; current skills live at a single flat <code>.archie/skills/</code> path with different naming</li><li>Bundled plugin loading via Yaegi from skill&#39;s <code>plugins/</code> directory -- not started, but <strong>has a working substrate to extend</strong>: <code>internal/gate/gateeval</code>, <code>internal/workflow/wfeval</code>, and <code>internal/skillscript</code> already interpret <code>.go</code> files via Yaegi with generated symbol tables and panic recovery (see <code>docs/prds/yaegi-plugin-system.md</code>, Phases 1--3, done). This phase should teach thLine truncated
@@ -1 +0,0 @@
import{_ as s,o as a,c as i,a2 as t}from"./chunks/framework.BWuWLRhz.js";const g=JSON.parse('{"title":"archie-core v2 Architecture -- Design Document","description":"","frontmatter":{},"headers":[],"relativePath":"archive/archie-core-architecture.md","filePath":"archive/archie-core-architecture.md","lastUpdated":1785228410000}'),n={name:"archive/archie-core-architecture.md"};function o(l,e,r,d,c,p){return a(),i("div",null,[...e[0]||(e[0]=[t("",106)])])}const k=s(n,[["render",o]]);export{g as __pageData,k as default};
@@ -1,158 +0,0 @@
import{_ as i,o as a,c as n,a2 as e}from"./chunks/framework.BWuWLRhz.js";const c=JSON.parse('{"title":"archie-core Skills System -- PRD","description":"","frontmatter":{},"headers":[],"relativePath":"archive/archie-core-skills-prd-v2.md","filePath":"archive/archie-core-skills-prd-v2.md","lastUpdated":1785228410000}'),t={name:"archive/archie-core-skills-prd-v2.md"};function l(h,s,p,k,r,d){return a(),n("div",null,[...s[0]||(s[0]=[e(`<h1 id="archie-core-skills-system-prd" tabindex="-1">archie-core Skills System -- PRD <a class="header-anchor" href="#archie-core-skills-system-prd" aria-label="Permalink to &quot;archie-core Skills System -- PRD&quot;">​</a></h1><p><strong>Author:</strong> Archie (Hermes agent) <strong>Date:</strong> 2026-07-18 <strong>Status:</strong> Draft</p><hr><h2 id="what-archie-core-is" tabindex="-1">What archie-core is <a class="header-anchor" href="#what-archie-core-is" aria-label="Permalink to &quot;What archie-core is&quot;">​</a></h2><p>arcie-core is an LLM coding agent that responds to issues, queries, and commands on connected interfaces. The current MVP runs on GitHub: it receives issue assignments, analyses scope and requirements, implements changes in isolated worktrees, runs quality gates, and opens pull requests.</p><p>The skills system extends this with reusable playbooks that tell archie-core <strong>how</strong> to work on any given project.</p><hr><h2 id="_1-the-workflow-file-archie-yaml" tabindex="-1">1. The workflow file (<code>archie.yaml</code>) <a class="header-anchor" href="#_1-the-workflow-file-archie-yaml" aria-label="Permalink to &quot;1. The workflow file (\`archie.yaml\`)&quot;">​</a></h2><p>Every project can ship an <code>archie.yaml</code> that defines how archie-core should behave when working on that codebase. Without one, archie-core uses sensible defaults (read files, run bash, open PRs). With one, it knows the exact gates to pass, tools available, commit format, and which skills are relevant.</p><h3 id="_1-1-discovery" tabindex="-1">1.1 Discovery <a class="header-anchor" href="#_1-1-discovery" aria-label="Permalink to &quot;1.1 Discovery&quot;">​</a></h3><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>.archie.yaml (root of repo -- highest precedence)</span></span>
<span class="line"><span>archie.yaml (repo root)</span></span>
<span class="line"><span>.archie/archie.yaml (subdirectory, one level deep)</span></span></code></pre></div><h3 id="_1-2-schema" tabindex="-1">1.2 Schema <a class="header-anchor" href="#_1-2-schema" aria-label="Permalink to &quot;1.2 Schema&quot;">​</a></h3><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># archie.yaml</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">version</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;1&quot;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Project identity</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">project</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">my-go-service</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> language</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> repo</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">github.com/sam/my-go-service</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># How archie-core connects to this project</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">connection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> interfaces</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">github</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # respond to assigned issues</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">linear</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # respond to labelled tickets</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">webhook</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # respond to HTTP POSTs</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> github</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> repo</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">sam/my-go-service</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> issue_labels</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> ready</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;archie:ready&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # issues with this label get claimed</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> claimed</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;archie:claimed&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # archie sets this when working</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> done</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;archie:done&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # archie sets this after PR</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> pr</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> base</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">main</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> draft</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Skills -- playbooks archie-core loads to know how to work</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">skills</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> paths</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.archie/skills/</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # project-local skills</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">~/.archie/skills/</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # per-user skills</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> remotes</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">github.com/sam/archie-skills@v1</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # shared skill library</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Sandbox -- what&#39;s available in the container</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">sandbox</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> image</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">ghcr.io/sam/archie-sandbox:latest</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> tools</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">golangci-lint</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">gofumpt</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">task</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">gh</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">docker</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> env</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> GOFLAGS</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;-mod=readonly&quot;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Gates -- archie-core must pass these before committing</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">gates</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go test -race -count=1 ./...</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> timeout</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">300</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> lint</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">golangci-lint run ./...</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> timeout</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">120</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> format</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">gofumpt -w . &amp;&amp; git diff --exit-code</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> deadcode</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">task deadcode</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> optional</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Quality pipeline -- which gates run when</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">quality</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> pre_commit</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">lint</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">format</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> pre_push</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">deadcode</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Commit conventions</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">commit</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> format</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">conventional</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> signoff</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Branch conventions</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">branch</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> format</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;{type}/cat-{number}-{kebab-description}&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> types</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> feat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Feature work&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> fix</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Bug fixes&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Test additions&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> chore</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Maintenance&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> refactor</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Code restructuring&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> docs</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Documentation&quot;</span></span></code></pre></div><hr><h2 id="_2-skills-playbooks" tabindex="-1">2. Skills (playbooks) <a class="header-anchor" href="#_2-skills-playbooks" aria-label="Permalink to &quot;2. Skills (playbooks)&quot;">​</a></h2><p>Skills are Markdown documents that tell archie-core <strong>how</strong> to perform specific tasks. They follow the <a href="https://agentskills.io/specification" target="_blank" rel="noreferrer">agentskills.io</a> format, making them portable across compatible LLM coding agents.</p><h3 id="_2-1-format" tabindex="-1">2.1 Format <a class="header-anchor" href="#_2-1-format" aria-label="Permalink to &quot;2.1 Format&quot;">​</a></h3><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>go-testing/</span></span>
<span class="line"><span>├── SKILL.md # Required: frontmatter + instructions</span></span>
<span class="line"><span>├── references/ # Optional: supplementary docs</span></span>
<span class="line"><span>│ └── coverage.md</span></span>
<span class="line"><span>├── scripts/ # Optional: executable helpers</span></span>
<span class="line"><span>│ └── bench.sh</span></span>
<span class="line"><span>└── assets/ # Optional: templates</span></span>
<span class="line"><span> └── test.vscode.code-snippets</span></span></code></pre></div><h3 id="_2-2-skill-md" tabindex="-1">2.2 SKILL.md <a class="header-anchor" href="#_2-2-skill-md" aria-label="Permalink to &quot;2.2 SKILL.md&quot;">​</a></h3><div class="language-markdown vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">markdown</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">---</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go-quality-gate</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> Run the full Go quality pipeline:</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> gofumpt, go fix, golangci-lint, go test -race, and task deadcode.</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> Use before any commit in a Go project.</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">version</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1.0.0</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">metadata</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> archie</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Which gates this skill covers</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> gates</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">lint</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">format</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">deadcode</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Required sandbox tools</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> tools</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">golangci-lint</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">gofumpt</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">task</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Preferred engine (if multiple available)</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> engine</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">any</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Max spend for this skill</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> budget_usd</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">2.00</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">---</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;"># Go Quality Gate</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">## When to use</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">Before committing any Go change. After implementing a feature or fix.</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">## Procedure</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">Run in this exact order. If any step fails, fix the issue before continuing.</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">1.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \`gofumpt -w .\`</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">2.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \`go fix ./...\`</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">3.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \`golangci-lint run ./...\`</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">4.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \`go test -race -count=1 ./...\`</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">5.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \`task deadcode\`</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">## Verification</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">All five steps must exit 0. If </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\`task deadcode\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> fails on unrelated packages,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">scope it to only changed packages: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\`golangci-lint run --tests=false --enable-only=unused,staticcheck ./changed/pkg/...\`</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">## Common failures</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \`golangci-lint\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: unused function -- remove it or add </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\`//nolint:unused\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> comment</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \`go test -race\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: data race -- protect with mutex or channel</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \`task deadcode\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: pre-existing dead code in unrelated package -- scope to changed packages</span></span></code></pre></div><h3 id="_2-3-skill-metadata-arcie-specific" tabindex="-1">2.3 Skill metadata (arcie-specific) <a class="header-anchor" href="#_2-3-skill-metadata-arcie-specific" aria-label="Permalink to &quot;2.3 Skill metadata (arcie-specific)&quot;">​</a></h3><p>Skills carry archie-specific metadata under <code>metadata.archie</code>:</p><table tabindex="0"><thead><tr><th>Field</th><th>Purpose</th></tr></thead><tbody><tr><td><code>gates</code></td><td>Which gates from <code>archie.yaml</code> this skill covers</td></tr><tr><td><code>tools</code></td><td>Sandbox tools this skill needs</td></tr><tr><td><code>engine</code></td><td>Preferred execution engine</td></tr><tr><td><code>model</code></td><td>Preferred model for this skill</td></tr><tr><td><code>budget_usd</code></td><td>Max spend ceiling</td></tr><tr><td><code>timeout</code></td><td>Max seconds</td></tr><tr><td><code>worktree</code></td><td>Whether to create isolated worktree</td></tr></tbody></table><h3 id="_2-4-progressive-disclosure" tabindex="-1">2.4 Progressive disclosure <a class="header-anchor" href="#_2-4-progressive-disclosure" aria-label="Permalink to &quot;2.4 Progressive disclosure&quot;">​</a></h3><p>Following the skills.sh model to keep context lean:</p><ol><li><strong>Advertise</strong> (~100 tokens per skill): <code>name</code> + <code>description</code> loaded at startup</li><li><strong>Activate</strong> (&lt;5000 tokens): Full SKILL.md body loaded when skill is relevant</li><li><strong>Resources</strong> (as needed): References, scripts, assets loaded on demand</li></ol><hr><h2 id="_3-how-archie-core-processes-an-issue" tabindex="-1">3. How archie-core processes an issue <a class="header-anchor" href="#_3-how-archie-core-processes-an-issue" aria-label="Permalink to &quot;3. How archie-core processes an issue&quot;">​</a></h2><p>This is the core loop. When an issue lands with the configured label:</p><h3 id="_3-1-analyse" tabindex="-1">3.1 Analyse <a class="header-anchor" href="#_3-1-analyse" aria-label="Permalink to &quot;3.1 Analyse&quot;">​</a></h3><ol><li>Read issue title, body, labels, comments</li><li>Load relevant skills from the project&#39;s <code>archie.yaml</code></li><li>Determine scope: which packages, files, and gates are in play</li><li>Determine branch type (<code>feat/</code>, <code>fix/</code>, <code>test/</code>, etc.) from issue labels or conventional commit prefix</li></ol><h3 id="_3-2-claim" tabindex="-1">3.2 Claim <a class="header-anchor" href="#_3-2-claim" aria-label="Permalink to &quot;3.2 Claim&quot;">​</a></h3><ol><li>Set issue label to <code>archie:claimed</code></li><li>Comment: &quot;Archie claimed this. Branch: <code>&lt;branch&gt;</code>&quot;</li><li>Create isolated worktree from <code>main</code></li></ol><h3 id="_3-3-implement" tabindex="-1">3.3 Implement <a class="header-anchor" href="#_3-3-implement" aria-label="Permalink to &quot;3.3 Implement&quot;">​</a></h3><ol><li>Load full skill bodies for each relevant skill</li><li>Read project source and tests in the affected area</li><li>Implement changes, writing tests first where applicable</li><li>Run targeted tests iteratively</li></ol><h3 id="_3-4-gate" tabindex="-1">3.4 Gate <a class="header-anchor" href="#_3-4-gate" aria-label="Permalink to &quot;3.4 Gate&quot;">​</a></h3><ol><li>Run all gates from the quality pipeline in order</li><li>Fix any failures, re-running from the failing gate</li><li>Audit diff for secrets, unrelated changes, attribution</li></ol><h3 id="_3-5-deliver" tabindex="-1">3.5 Deliver <a class="header-anchor" href="#_3-5-deliver" aria-label="Permalink to &quot;3.5 Deliver&quot;">​</a></h3><ol><li>Commit with conventional format: <code>feat(scope): description</code></li><li>Push branch</li><li>Open PR to <code>main</code> with: <ul><li>Summary of changes</li><li>Acceptance criteria addressed</li><li>Gate results</li><li>Link back to source issue/Linear ticket</li></ul></li><li>Set issue label to <code>archie:done</code></li><li>Comment with PR URL</li></ol><h3 id="_3-6-on-failure" tabindex="-1">3.6 On failure <a class="header-anchor" href="#_3-6-on-failure" aria-label="Permalink to &quot;3.6 On failure&quot;">​</a></h3><p>If any gate fails irrecoverably:</p><ol><li>Leave issue as <code>archie:claimed</code></li><li>Comment with exact blocker, failed command, and worktree path</li><li>Preserve worktree for inspection</li><li>Do not open a broken PR</li></ol><hr><h2 id="_4-engine-abstraction" tabindex="-1">4. Engine abstraction <a class="header-anchor" href="#_4-engine-abstraction" aria-label="Permalink to &quot;4. Engine abstraction&quot;">​</a></h2><p>arcie-core can delegate implementation to dLine truncated
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">claude</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Claude Code CLI -- full agent loop</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">sonnet</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> budget_usd</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">5.00</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">codex</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # OpenAI Codex CLI</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">gpt-5.1-codex-max</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">raw</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Direct LLM -- no agent loop, single prompt</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">gpt-4o-mini</span></span></code></pre></div><p>Each engine provides the same interface:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>Engine:</span></span>
<span class="line"><span> - Run(prompt, tools, budget, timeout) -&gt; Result</span></span>
<span class="line"><span> - Skills() -&gt; []SkillName</span></span>
<span class="line"><span> - Capabilities() -&gt; {streaming, reasoning, vision, agentic}</span></span></code></pre></div><p>For skills that need a specific engine, the skill metadata overrides:</p><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">metadata</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> archie</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> engine</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">claude</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # this skill only works with Claude</span></span></code></pre></div><hr><h2 id="_5-skills-in-practice" tabindex="-1">5. Skills in practice <a class="header-anchor" href="#_5-skills-in-practice" aria-label="Permalink to &quot;5. Skills in practice&quot;">​</a></h2><h3 id="_5-1-shared-skill-library" tabindex="-1">5.1 Shared skill library <a class="header-anchor" href="#_5-1-shared-skill-library" aria-label="Permalink to &quot;5.1 Shared skill library&quot;">​</a></h3><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># archie.yaml</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">skills</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> remotes</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">github.com/sam/archie-skills@v1</span></span></code></pre></div><p>Skills from the shared library are available alongside project-local skills. The agent loads them on demand when an issue references relevant concepts.</p><h3 id="_5-3-skill-that-wraps-an-external-tool" tabindex="-1">5.3 Skill that wraps an external tool <a class="header-anchor" href="#_5-3-skill-that-wraps-an-external-tool" aria-label="Permalink to &quot;5.3 Skill that wraps an external tool&quot;">​</a></h3><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">---</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">trivy-scan</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> Scan container images and filesystems for vulnerabilities using Trivy.</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> Use when asked about security scanning, CVEs, or container hardening.</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">metadata</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> archie</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> tools</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">docker</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">trivy</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> engine</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">any</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">---</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">## Procedure</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">1. \`trivy image --severity HIGH,CRITICAL &lt;image&gt;\`</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">2. If findings exist, report each CVE with package, version, and fixed version</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">3. If no findings, report clean</span></span></code></pre></div><hr><h2 id="_6-comparison-archie-core-vs-existing-systems" tabindex="-1">6. Comparison: archie-core vs existing systems <a class="header-anchor" href="#_6-comparison-archie-core-vs-existing-systems" aria-label="Permalink to &quot;6. Comparison: archie-core vs existing systems&quot;">​</a></h2><table tabindex="0"><thead><tr><th></th><th>archie-core</th><th>Claude Code</th><th>Codex CLI</th><th>GitHub Actions</th><th>Hermes Agent</th></tr></thead><tbody><tr><td><strong>How it receives work</strong></td><td>GitHub issue assignment, Linear label, webhook</td><td>Chat, slash commands</td><td>Chat, slash commands</td><td>YAML triggers (push, PR, schedule)</td><td>Chat, cron, webhooks</td></tr><tr><td><strong>What it does</strong></td><td>Analyse → implement → gate → PR</td><td>Analyse → implement → gate → PR</td><td>Analyse → implement → gate → PR</td><td>Run arbitrary shell commands</td><td>Analyse → implement → gate → PR</td></tr><tr><td><strong>Skills</strong></td><td>SKILL.md (agentskills.io)</td><td>SKILL.md (native)</td><td>SKILL.md (agentskills.io)</td><td>Composite actions</td><td>SKILL.md (native)</td></tr><tr><td><strong>Gates</strong></td><td>Named checkpoints in archie.yaml</td><td>Ad-hoc (CLAUDE.md + lint)</td><td>Ad-hoc</td><td>Steps in jobs</td><td>Skills with gates</td></tr><tr><td><strong>Engine pluggable</strong></td><td>Yes</td><td>No (fixed to Claude)</td><td>No (fixed to Codex)</td><td>No (fixed to GitHub)</td><td>Yes (provider config)</td></tr><tr><td><strong>Worktree isolation</strong></td><td>Yes</td><td>Yes (<code>--worktree</code>)</td><td>No</td><td>No (ephemeral runner)</td><td>No</td></tr><tr><td><strong>Blueprint/cron</strong></td><td>Export to Hermes</td><td>No</td><td>No</td><td>Schedule trigger</td><td>Native</td></tr><tr><td><strong>Where it runs</strong></td><td>Docker sandbox</td><td>Host</td><td>Host or sandbox</td><td>GitHub runner</td><td>Host, Docker, Modal, SSH</td></tr></tbody></table><hr><h2 id="_7-implementation-phases" tabindex="-1">7. Implementation phases <a class="header-anchor" href="#_7-implementation-phases" aria-label="Permalink to &quot;7. Implementation phases&quot;">​</a></h2><h3 id="phase-1-workflow-file-and-gates-current-mvp" tabindex="-1">Phase 1: Workflow file and gates (current MVP) <a class="header-anchor" href="#phase-1-workflow-file-and-gates-current-mvp" aria-label="Permalink to &quot;Phase 1: Workflow file and gates (current MVP)&quot;">​</a></h3><ul><li><code>archie.yaml</code> parser</li><li>Gate runner executing shell commands and checking exit codes</li><li>Skill discovery from project and user paths</li><li>GitHub interface: claim issues, create worktrees, open PRs</li></ul><h3 id="phase-2-skills" tabindex="-1">Phase 2: Skills <a class="header-anchor" href="#phase-2-skills" aria-label="Permalink to &quot;Phase 2: Skills&quot;">​</a></h3><ul><li>SKILL.md progressive disclosure (advertise → activate → resources)</li><li>archie-specific metadata parsing</li><li>Skill chaining: skills that depend on other skills</li><li><code>archie skills list/install</code> CLI</li></ul><h3 id="phase-3-engine-abstraction" tabindex="-1">Phase 3: Engine abstraction <a class="header-anchor" href="#phase-3-engine-abstraction" aria-label="Permalink to &quot;Phase 3: Engine abstraction&quot;">​</a></h3><ul><li>Engine interface definition</li><li>Claude Code adapter</li><li>Raw LLM adapter</li><li>Engine fallback chain</li><li>Per-skill engine preferences</li></ul><h3 id="phase-4-advanced-features" tabindex="-1">Phase 4: Advanced features <a class="header-anchor" href="#phase-4-advanced-features" aria-label="Permalink to &quot;Phase 4: Advanced features&quot;">​</a></h3><ul><li>Gate overrides per skill</li><li>Skill templates for project scaffolding (<code>archie init --skill go-service</code>)</li><li>Remote skill libraries (git repos as skill sources)</li><li>Blueprint export to Hermes cron</li></ul><h3 id="phase-5-additional-interfaces" tabindex="-1">Phase 5: Additional interfaces <a class="header-anchor" href="#phase-5-additional-interfaces" aria-label="Permalink to &quot;Phase 5: Additional interfaces&quot;">​</a></h3><ul><li>Linear webhook integration</li><li>Generic webhook interface for arbitrary sources</li><li>CLI command interface (<code>archie run &lt;command&gt;</code>)</li></ul><hr><h2 id="_8-open-questions" tabindex="-1">8. Open questions <a class="header-anchor" href="#_8-open-questions" aria-label="Permalink to &quot;8. Open questions&quot;">​</a></h2><ol><li><strong>Claim protocol:</strong> Single-claim (arcie takes one issue at a time) or queue-based (claims N issues, works through them sequentially)?</li><li><strong>Concurrent worktrees:</strong> Allow multiple archie-core instances working on different issues simultaneously?</li><li><strong>PR merging:</strong> ShoulLine truncated
@@ -1 +0,0 @@
import{_ as i,o as a,c as n,a2 as e}from"./chunks/framework.BWuWLRhz.js";const c=JSON.parse('{"title":"archie-core Skills System -- PRD","description":"","frontmatter":{},"headers":[],"relativePath":"archive/archie-core-skills-prd-v2.md","filePath":"archive/archie-core-skills-prd-v2.md","lastUpdated":1785228410000}'),t={name:"archive/archie-core-skills-prd-v2.md"};function l(h,s,p,k,r,d){return a(),n("div",null,[...s[0]||(s[0]=[e("",75)])])}const g=i(t,[["render",l]]);export{c as __pageData,g as default};
@@ -1,173 +0,0 @@
import{_ as i,o as a,c as n,a2 as e}from"./chunks/framework.BWuWLRhz.js";const c=JSON.parse('{"title":"archie-core Workflows & Skills -- Product Requirements Document","description":"","frontmatter":{},"headers":[],"relativePath":"archive/archie-core-skills-prd.md","filePath":"archive/archie-core-skills-prd.md","lastUpdated":1785228410000}'),t={name:"archive/archie-core-skills-prd.md"};function l(h,s,p,k,r,d){return a(),n("div",null,[...s[0]||(s[0]=[e(`<h1 id="archie-core-workflows-skills-product-requirements-document" tabindex="-1">archie-core Workflows &amp; Skills -- Product Requirements Document <a class="header-anchor" href="#archie-core-workflows-skills-product-requirements-document" aria-label="Permalink to &quot;archie-core Workflows &amp; Skills -- Product Requirements Document&quot;">​</a></h1><p><strong>Author:</strong> Archie (Hermes agent) <strong>Date:</strong> 2026-07-18 <strong>Status:</strong> Draft</p><hr><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p>This PRD defines a workflow and skills system for archie-core. Workflow files declare gates, tool availability, execution engines, and skill references. Skills are reusable playbook documents the agent loads on demand. Together they enable any project to define how agents work within their sandbox and select an available execution engine.</p><hr><h2 id="_1-workflow-files-archie-yaml" tabindex="-1">1. Workflow Files (<code>archie.yaml</code>) <a class="header-anchor" href="#_1-workflow-files-archie-yaml" aria-label="Permalink to &quot;1. Workflow Files (\`archie.yaml\`)&quot;">​</a></h2><h3 id="_1-1-discovery" tabindex="-1">1.1 Discovery <a class="header-anchor" href="#_1-1-discovery" aria-label="Permalink to &quot;1.1 Discovery&quot;">​</a></h3><p>A project declares its workflow in <code>archie.yaml</code> at the project root. archie-core discovers it the same way Task (Taskfile) and devcontainers do:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>.archie.yaml (root of repo -- highest precedence)</span></span>
<span class="line"><span>archie.yaml (repo root)</span></span>
<span class="line"><span>.archie/archie.yaml (subdirectory, one level deep)</span></span></code></pre></div><p>If no file is found, archie-core uses built-in defaults (read, write, bash).</p><h3 id="_1-2-schema" tabindex="-1">1.2 Schema <a class="header-anchor" href="#_1-2-schema" aria-label="Permalink to &quot;1.2 Schema&quot;">​</a></h3><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># archie.yaml -- complete schema</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">version</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;1&quot;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Project identity</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">project</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">my-go-service</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> language</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Available skills (directories or individual files)</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">skills</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> paths</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.archie/skills/</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # project-local skills</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">~/.archie/skills/</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # per-user skills</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">github.com/org/shared-skills@v1</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # remote skill repo</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> skills</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go-testing</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # named skill from any path</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">security-audit</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Execution engines in preference order</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">engines</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">claude</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Claude Code CLI</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">sonnet</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">codex</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # OpenAI Codex</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pi</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Pi agent harness</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">raw</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Direct LLM without agent wrapper</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Sandbox definition (what the Docker container provides)</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">sandbox</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> image</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">ghcr.io/samcharles93/archie-sandbox:latest</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> tools</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">golangci-lint</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">gofumpt</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">task</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">gh</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">docker</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> mounts</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/var/run/docker.sock</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> target</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/var/run/docker.sock</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> env</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> GOFLAGS</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;-mod=readonly&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> CGO_ENABLED</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;0&quot;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Gates -- ordered checkpoints that must pass</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">gates</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go test -race -count=1 ./...</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> timeout</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">300</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;All tests must pass&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> lint</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">golangci-lint run ./...</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> timeout</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">120</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Zero lint issues&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> format</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">gofumpt -w . &amp;&amp; git diff --exit-code</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;No formatting drift&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> vet</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go vet ./...</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;No vet warnings&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> deadcode</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">task deadcode</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> optional</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # non-blocking gate</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Dead code check (advisory)&quot;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Quality pipeline -- ordered sequence of gate groups</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">quality</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> pre_commit</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">test</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">lint</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">format</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">vet</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> pre_push</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">deadcode</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Commit conventions</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">commit</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> format</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">conventional</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # conventional commits</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> signoff</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> template</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;feat({scope}): {description}&quot;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># PR conventions</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">pr</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> template</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.github/PULL_REQUEST_TEMPLATE.md</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> checks</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">test</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">lint</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Project-specific commands (what \`archie run &lt;name&gt;\` executes)</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">commands</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> build</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go build -o bin/app ./cmd/server</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Build the binary&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> serve</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go run ./cmd/server</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Start dev server&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go test ./...</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Run all tests&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> lint</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">golangci-lint run ./...</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Run linter&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> all</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">gofumpt -w .</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go fix ./...</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">golangci-lint run ./...</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go test -race ./...</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">task deadcode</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Full quality pipeline&quot;</span></span></code></pre></div><h3 id="_1-3-design-decisions-with-rationale" tabindex="-1">1.3 Design decisions (with rationale) <a class="header-anchor" href="#_1-3-design-decisions-with-rationale" aria-label="Permalink to &quot;1.3 Design decisions (with rationale)&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Decision</th><th>Rationale</th></tr></thead><tbody><tr><td>YAML over TOML/JSON</td><td>Already dominant in CI (GitHub Actions, GitLab CI, Taskfile). Human-readable with comments.</td></tr><tr><td>Single file over multi-file</td><td>Task discovery (like <code>Taskfile.yml</code>), devcontainer conventions. Avoids directory sprawl.</td></tr><tr><td>Gates as named checkpoints</td><td>GitHub Actions job model. Gates can be composed into quality pipelines, selected individually, or skipped with <code>--skip</code>.</td></tr><tr><td>Engines as ordered preference list</td><td>Supports deterministic fallback between available engines. Each engine declares its own tool surface.</td></tr><tr><td>Skills as paths + references</td><td>Matches devcontainer features (paths resolve to directories) and skills.sh (namespaced references).</td></tr><tr><td>Commands section for direct invocation</td><td>Arnie can <code>archie run test</code> without an agent turn. Thin wrapper over the sandbox.</td></tr><tr><td>Quality pipeline groups gates</td><td>Pre-commit vs pre-push vs pre-merge distinction. Some gates are required, some advisory.</td></tr></tbody></table><hr><h2 id="_2-skills" tabindex="-1">2. Skills <a class="header-anchor" href="#_2-skills" aria-label="Permalink to &quot;2. Skills&quot;">​</a></h2><h3 id="_2-1-format" tabindex="-1">2.1 Format <a class="header-anchor" href="#_2-1-format" aria-label="Permalink to &quot;2.1 Format&quot;">​</a></h3><p>Skills follow the <a href="https://agentskills.io/specification" target="_blank" rel="noreferrer">agentskills.io</a> specification:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>skill-name/</span></span>
<span class="line"><span>├── SKILL.md # Required: YAML frontmatter + Markdown instructions</span></span>
<span class="line"><span>├── scripts/ # Optional: executable helpers</span></span>
<span class="line"><span>├── references/ # Optional: longer docs, checklists</span></span>
<span class="line"><span>└── assets/ # Optional: templates, configs</span></span></code></pre></div><p><strong>SKILL.md frontmatter:</strong></p><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">---</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go-testing</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> Run Go tests with race detection, coverage, and benchmark analysis.</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> Use when asked to test Go code, run the test suite, or check coverage.</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">version</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1.0.0</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">metadata</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> archie</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> gates</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># gates this skill requires</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> tools</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">golangci-lint</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># sandbox tools it needs</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> engine</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">any</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # engine preference</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">compatibility</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">Requires Go 1.22+</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">---</span></span></code></pre></div><h3 id="_2-2-progressive-disclosure" tabindex="-1">2.2 Progressive disclosure <a class="header-anchor" href="#_2-2-progressive-disclosure" aria-label="Permalink to &quot;2.2 Progressive disclosure&quot;">​</a></h3><p>Following the skills.sh and Claude Code patterns:</p><ol><li><strong>Advertise</strong> (~100 tokens): <code>name</code> + <code>description</code> loaded at session start</li><li><strong>Load</strong> (&lt;5000 tokens recommended): Full SKILL.md body when skill activates</li><li><strong>Resources</strong> (as needed): Scripts, references, assets loaded on demand</li></ol><h3 id="_2-3-archie-specific-metadata" tabindex="-1">2.3 archie-specific metadata <a class="header-anchor" href="#_2-3-archie-specific-metadata" aria-label="Permalink to &quot;2.3 archie-specific metadata&quot;">​</a></h3><p>Skills can carry archie-specific frontmatter under <code>metadata.archie</code>:</p><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">metadata</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> archie</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> gates</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">lint</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># must-pass gates before skill runs</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> tools</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">docker</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># sandbox tools required</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> engine</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">any</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # preferred engine</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">gpt-4o</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # preferred model</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> budget_usd</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">2.00</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # max spend ceiling</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> timeout</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">600</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # max seconds</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> worktree</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # create isolated worktree</span></span></code></pre></div><h3 id="_2-4-skill-sources-inspired-by-devcontainer-features-dagger-modules" tabindex="-1">2.4 Skill sources (inspired by devcontainer features + Dagger modules) <a class="header-anchor" href="#_2-4-skill-sources-inspired-by-devcontainer-features-dagger-modules" aria-label="Permalink to &quot;2.4 Skill sources (inspired by devcontainer features + Dagger modules)&quot;">​</a></h3><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>skills:</span></span>
<span class="line"><span> paths:</span></span>
<span class="line"><span> - .archie/skills/ # project-local (committed)</span></span>
<span class="line"><span> - ~/.archie/skills/ # per-user (personal)</span></span>
<span class="line"><span> skills:</span></span>
<span class="line"><span> - go-testing # by name from any path</span></span>
<span class="line"><span> remotes:</span></span>
<span class="line"><span> - github.com/samcharles93/archie-skills@v1 # tagged git repo</span></span>
<span class="line"><span> - https://agentskills.io/registry # community registry</span></span></code></pre></div><hr><h2 id="_3-execution-engine-model" tabindex="-1">3. Execution Engine Model <a class="header-anchor" href="#_3-execution-engine-model" aria-label="Permalink to &quot;3. Execution Engine Model&quot;">​</a></h2><h3 id="_3-1-engine-abstraction" tabindex="-1">3.1 Engine abstraction <a class="header-anchor" href="#_3-1-engine-abstraction" aria-label="Permalink to &quot;3.1 Engine abstraction&quot;">​</a></h3><p>Each engine provides the same interface. The workflow file declares preference order; archie-core resolves the first available engine at runtime.</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>Engine interface:</span></span>
<span class="line"><span> - Run(prompt, tools[], budget, timeout) -&gt; Result</span></span>
<span class="line"><span> - Tools() -&gt; []ToolSchema</span></span>
<span class="line"><span> - Capabilities() -&gt; {streaming, reasoning, vision, agentic}</span></span></code></pre></div><h3 id="_3-2-supported-engines" tabindex="-1">3.2 Supported engines <a class="header-anchor" href="#_3-2-supported-engines" aria-label="Permalink to &quot;3.2 Supported engines&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Engine</th><th>Type</th><th>What it provides</th></tr></thead><tbody><tr><td><code>claude</code></td><td>Claude Code CLI</td><td>Full agent loop, tool use, worktrees, subagents</td></tr><tr><td><code>codex</code></td><td>OpenAI Codex CLI</td><td>Agentic coding with sandbox</td></tr><tr><td><code>pi</code></td><td>Pi agent harness</td><td>Minimalist coding agent, stdio protocol</td></tr><tr><td><code>raw</code></td><td>Direct LLM call</td><td>Single-turn prompt, no agent loop. For simple scripts.</td></tr></tbody></table><h3 id="_3-3-engine-selection-logic" tabindex="-1">3.3 Engine selection logic <a class="header-anchor" href="#_3-3-engine-selection-logic" aria-label="Permalink to &quot;3.3 Engine selection logic&quot;">​</a></h3><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">engines</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">claude</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">sonnet</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> budget_usd</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">5.00</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">raw</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">gpt-4o-mini</span></span></code></pre></div><p>arcie-core tries engines in order and selects the first available, authenticated engine. Each engine declares its budget ceiling.</p><hr><h2 id="_4-additional-features" tabindex="-1">4. Additional Features <a class="header-anchor" href="#_4-additional-features" aria-label="Permalink to &quot;4. Additional Features&quot;">​</a></h2><h3 id="_4-1-worktree-isolation-worktree-true" tabindex="-1">4.1 Worktree isolation (<code>worktree: true</code>) <a class="header-anchor" href="#_4-1-worktree-isolation-worktree-true" aria-label="Permalink to &quot;4.1 Worktree isolation (\`worktree: true\`)&quot;">​</a></h3><p>Inspired by Claude Code&#39;s <code>--worktree</code> flag. When a skill or command sets <code>worktree: true</code>, archie-core:</p><ol><li>Creates an isolated git worktree at <code>.archie/worktrees/&lt;skill-name&gt;-&lt;timestamp&gt;/</code></li><li>Runs all gates and implementation in that worktree</li><li>Cleans up on success, preserves on failure for inspection</li></ol><p>This prevents concurrent agent sessions from conflicting and enables parallel agent execution.</p><h3 id="_4-2-skill-chaining-and-composition" tabindex="-1">4.2 Skill chaining and composition <a class="header-anchor" href="#_4-2-skill-chaining-and-composition" aria-label="Permalink to &quot;4.2 Skill chaining and composition&quot;">​</a></h3><p>Skills can declare dependencies, forming a DAG:</p><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">---</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">full-ci</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">Complete CI pipeline including security audit</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">metadata</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> archie</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> requires</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go-testing</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">security-audit</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run_sequential</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">---</span></span></code></pre></div><p>arcie-core resolves the dependency graph and runs skills in order (parallel where possible, respecting <code>run_sequential</code>). This is conceptually similar to GitHub Actions <code>needs</code> and Taskfile <code>deps</code>.</p><h3 id="_4-3-gate-overrides-per-skill" tabindex="-1">4.3 Gate overrides per skill <a class="header-anchor" href="#_4-3-gate-overrides-per-skill" aria-label="Permalink to &quot;4.3 Gate overrides per skill&quot;">​</a></h3><p>A skill can override project-level gates:</p><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">metadata</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> archie</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> gates</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">go test -short ./...</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # override: faster test for this skill</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> lint</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">skip</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # skip lint for this skill</span></span></code></pre></div><p>Three override modes: <code>override</code> (replace command), <code>skip</code> (omit gate), <code>add</code> (add new gate requirement).</p><h3 id="_4-4-skill-templates-scaffolding" tabindex="-1">4.4 Skill templates (scaffolding) <a class="header-anchor" href="#_4-4-skill-templates-scaffolding" aria-label="Permalink to &quot;4.4 Skill templates (scaffolding)&quot;">​</a></h3><p>Skills can carry an <code>assets/</code> directory with templates. When archie-core initializes a new project, it can apply skill templates:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>skill-name/</span></span>
<span class="line"><span>├── SKILL.md</span></span>
<span class="line"><span>└── assets/</span></span>
<span class="line"><span> ├── .archie.yaml.tmpl # Template workflow file</span></span>
<span class="line"><span> ├── Taskfile.yml.tmpl # Template task runner</span></span>
<span class="line"><span> └── .golangci.yml.tmpl # Template linter config</span></span></code></pre></div><p><code>archie init --skill go-service</code> scaffolds a new project with the go-service skill&#39;s templates applied.</p><h3 id="_4-5-blueprint-export-hermes-cron-integration" tabindex="-1">4.5 Blueprint export (Hermes cron integration) <a class="header-anchor" href="#_4-5-blueprint-export-hermes-cron-integration" aria-label="Permalink to &quot;4.5 Blueprint export (Hermes cron integration)&quot;">​</a></h3><p>Following the Hermes Automation Blueprints model, any archie-core workflow can be exported as a Hermes blueprint:</p><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">metadata</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> archie</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> blueprint</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> schedule</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;every 6h&quot;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> deliver</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">telegram</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;CI monitor&quot;</span></span></code></pre></div><p>The export produces a <code>SKILL.md</code> with <code>metadata.hermes.blueprint</code> that Hermes can schedule. The blueprint&#39;s prompt is the archie workflow&#39;s quality pipeline.</p><hr><h2 id="_5-comparison-to-existing-systems" tabindex="-1">5. Comparison to Existing Systems <a class="header-anchor" href="#_5-comparison-to-existing-systems" aria-label="Permalink to &quot;5. Comparison to Existing Systems&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Feature</th><th>archie-core</th><th>GitHub Actions</th><th>Dagger</th><th>Taskfile</th><th>devcontainer</th><th>Hermes Skills</th></tr></thead><tbody><tr><td>Language</td><td>YAML</td><td>YAML</td><td>Go/Python/TS</td><td>YAML</td><td>JSON</td><td>Markdown</td></tr><tr><td>Gates</td><td>Named + composable</td><td>Steps in jobs</td><td>Functions</td><td>Tasks</td><td>Lifecycle scripts</td><td>N/A</td></tr><tr><td>Engine abstraction</td><td>First-class</td><td>GitHub only</td><td>Dagger Engine</td><td>Shell only</td><td>None</td><td>Provider</td></tr><tr><td>Skills</td><td>agentskills.io spec</td><td>Composite actions</td><td>Dagger Modules</td><td>Includes</td><td>Features</td><td>SKILL.md</td></tr><tr><td>Worktree isolation</td><td>Built-in</td><td>No</td><td>Containers</td><td>No</td><td>Container</td><td>No</td></tr><tr><td>Blueprint export</td><td>To Hermes cron</td><td>No</td><td>No</td><td>No</td><td>No</td><td>Native</td></tr><tr><td>Multi-engine fallback</td><td>Yes (ordered list)</td><td>No</td><td>No</td><td>No</td><td>No</td><td>Provider config</td></tr><tr><td>Progressive disclosure</td><td>Yes (skill spec)</td><td>No</td><td>No</td><td>No</td><td>Feature metadata</td><td>Yes</td></tr></tbody></table><hr><h2 id="_6-implementation-phases" tabindex="-1">6. Implementation Phases <a class="header-anchor" href="#_6-implementation-phases" aria-label="Permalink to &quot;6. Implementation Phases&quot;">​</a></h2><h3 id="phase-1-core-workflow-file" tabindex="-1">Phase 1: Core workflow file <a class="header-anchor" href="#phase-1-core-workflow-file" aria-label="Permalink to &quot;Phase 1: Core workflow file&quot;">​</a></h3><ul><li><code>archie.yaml</code> parser and schema validation</li><li>Gate runner (test, lint, format, vet)</li><li><code>archie run &lt;command&gt;</code> CLI</li><li>Sandbox Docker integration</li></ul><h3 id="phase-2-skills" tabindex="-1">Phase 2: Skills <a class="header-anchor" href="#phase-2-skills" aria-label="Permalink to &quot;Phase 2: Skills&quot;">​</a></h3><ul><li>SKILL.md discovery and progressive disclosure</li><li>Skill metadata with gate/tool/engine requirements</li><li><code>archie skills list/install/search</code></li></ul><h3 id="phase-3-engine-abstraction" tabindex="-1">Phase 3: Engine abstraction <a class="header-anchor" href="#phase-3-engine-abstraction" aria-label="Permalink to &quot;Phase 3: Engine abstraction&quot;">​</a></h3><ul><li>Engine interface definition</li><li>Claude Code adapter</li><li>Raw LLM adapter</li><li>Engine fallback chain</li></ul><h3 id="phase-4-advanced-features" tabindex="-1">Phase 4: Advanced features <a class="header-anchor" href="#phase-4-advanced-features" aria-label="Permalink to &quot;Phase 4: Advanced features&quot;">​</a></h3><ul><li>Worktree isolation</li><li>Skill chaining (dependency DAG)</li><li>Gate overrides</li><li>Blueprint export</li></ul><h3 id="phase-5-ecosystem" tabindex="-1">Phase 5: Ecosystem <a class="header-anchor" href="#phase-5-ecosystem" aria-label="Permalink to &quot;Phase 5: Ecosystem&quot;">​</a></h3><ul><li>Public skill registry</li><li><code>archie init --skill &lt;name&gt;</code> scaffolding</li><li>Community skill contributions</li></ul><hr><h2 id="_7-open-questions" tabindex="-1">7. Open Questions <a class="header-anchor" href="#_7-open-questions" aria-label="Permalink to &quot;7. Open Questions&quot;">​</a></h2><ol><li><strong>Skill registry hosting:</strong> Self-hosted on git.catlow.cloud, or use agentskills.io?</li><li><strong>Hermes integration:</strong> Should archie-core be a Hermes tool, a Hermes skill, or standalone?</li><li><strong>Budget enforcement:</strong> Per-skill budget vs. per-workflow budget vs. monthly cap?</li><li><strong>Sandbox image building:</strong> Pre-built images vs. Dockerfile in each skill?</li></ol>`,80)])])}const E=i(t,[["render",l]]);export{c as __pageData,E as default};
@@ -1 +0,0 @@
import{_ as i,o as a,c as n,a2 as e}from"./chunks/framework.BWuWLRhz.js";const c=JSON.parse('{"title":"archie-core Workflows & Skills -- Product Requirements Document","description":"","frontmatter":{},"headers":[],"relativePath":"archive/archie-core-skills-prd.md","filePath":"archive/archie-core-skills-prd.md","lastUpdated":1785228410000}'),t={name:"archive/archie-core-skills-prd.md"};function l(h,s,p,k,r,d){return a(),n("div",null,[...s[0]||(s[0]=[e("",80)])])}const E=i(t,[["render",l]]);export{c as __pageData,E as default};
@@ -1 +0,0 @@
import{_ as o,o as t,c as a,a2 as s}from"./chunks/framework.BWuWLRhz.js";const p=JSON.parse('{"title":"Archie Design Decisions","description":"","frontmatter":{},"headers":[],"relativePath":"archive/decisions.md","filePath":"archive/decisions.md","lastUpdated":1785228410000}'),r={name:"archive/decisions.md"};function n(i,e,d,c,l,g){return t(),a("div",null,[...e[0]||(e[0]=[s('<h1 id="archie-design-decisions" tabindex="-1">Archie Design Decisions <a class="header-anchor" href="#archie-design-decisions" aria-label="Permalink to &quot;Archie Design Decisions&quot;">​</a></h1><p>Record of architectural choices, reversals, and lessons learned during development. Each entry has a date, a decision, the reasoning, and the context that led to it. This document is the first thing to read before changing anything that contradicts a prior decision.</p><hr><h2 id="_2026-07-23-forge-agnostic-issue-creation-via-createissue" tabindex="-1">2026-07-23 -- Forge-agnostic issue creation via CreateIssue <a class="header-anchor" href="#_2026-07-23-forge-agnostic-issue-creation-via-createissue" aria-label="Permalink to &quot;2026-07-23 -- Forge-agnostic issue creation via CreateIssue&quot;">​</a></h2><p><strong>Decision</strong>: Add <code>CreateIssue(ctx, owner, repo, title, body, labels) (int, error)</code> to the <code>forge.Forge</code> interface. Every forge backend (Gitea, GitHub, future beads) implements it.</p><p><strong>Reasoning</strong>: Agents discover out-of-scope findings during planning and building. These should be filed as tickets immediately rather than lost. Making <code>CreateIssue</code> part of the Forge interface means the agent calls one method regardless of the underlying ticketing system.</p><p><strong>Future</strong>: A <code>beads</code> forge backend will implement <code>CreateIssue</code> by calling <code>bd create</code>. This makes beads the internal/default issue tracker while Gitea/GitHub are external forges. The agent doesn&#39;t know which it&#39;s talking to -- the daemon resolves the forge from repo config.</p><hr><h2 id="_2026-07-23-dolt-and-beads-for-agent-native-issue-tracking" tabindex="-1">2026-07-23 -- Dolt and Beads for agent-native issue tracking <a class="header-anchor" href="#_2026-07-23-dolt-and-beads-for-agent-native-issue-tracking" aria-label="Permalink to &quot;2026-07-23 -- Dolt and Beads for agent-native issue tracking&quot;">​</a></h2><p><strong>Decision</strong>: Install dolt (version-controlled SQL) and beads (<code>bd</code>, a graph-based issue tracker for AI agents) as the foundation for multi-repo scaling and multi-agent coordination.</p><p><strong>Reasoning</strong>: Beads provides persistent memory across sessions, first- class dependency tracking, JSON output for programmatic use, and hash- based IDs that prevent merge conflicts in multi-agent workflows. It&#39;s built on Dolt which gives cell-level merge, native branching, and remote sync -- the same primitives git gives code but applied to issues.</p><p><strong>Context</strong>: Gas Town (<code>~/gt/</code>) is cloned for reference -- it implements a multi-agent workspace on top of beads. The archie-core scaling strategy will follow a similar model: a coordinator daemon with per-repo agents, all sharing a beads-backed task graph.</p><p><strong>Current state</strong>: dolt 2.2.2, beads 1.1.0 installed. Beads initialized in archie-core (<code>.beads/</code>). Six issues seeded for the scaling roadmap.</p><hr><h2 id="_2026-07-23-token-budgets-must-be-generous-not-predictive" tabindex="-1">2026-07-23 -- Token budgets must be generous, not predictive <a class="header-anchor" href="#_2026-07-23-token-budgets-must-be-generous-not-predictive" aria-label="Permalink to &quot;2026-07-23 -- Token budgets must be generous, not predictive&quot;">​</a></h2><p><strong>Decision</strong>: Set <code>max_tokens</code> to 100,000,000 (100M). Do not attempt to predict what a task needs without data. Lower limits later based on actual per-workflow/per-repo metrics.</p><p><strong>Reasoning</strong>: An agent killed mid-task at 1M tokens wastes every token it already consumed. There is no compaction or checkpointing yet, so a killed agent is a total loss. Hermes regularly uses 160+ steps and hundreds of thousands of tokens per request. Large repositories need proportionally more.</p><p><strong>Context</strong>: The planner burned 357K tokens just to discover a fix already existed. The builder hit 1M at step 25 of 90. Neither task was unreasonable -- they were just exploring a large codebase.</p><p><strong>Future</strong>: Track actual token consumption per workflow/stage/repo. Use that data to set informed limits. Build compaction or checkpointing so a killed agent can resume rather than restart.</p><hr><h2 id="_2026-07-23-baseline-fix-auto-repair-pre-existing-gate-failures" tabindex="-1">2026-07-23 -- baseline-fix: auto-repair pre-existing gate failures <a class="header-anchor" href="#_2026-07-23-baseline-fix-auto-repair-pre-Line truncated
@@ -1 +0,0 @@
import{_ as o,o as t,c as a,a2 as s}from"./chunks/framework.BWuWLRhz.js";const p=JSON.parse('{"title":"Archie Design Decisions","description":"","frontmatter":{},"headers":[],"relativePath":"archive/decisions.md","filePath":"archive/decisions.md","lastUpdated":1785228410000}'),r={name:"archive/decisions.md"};function n(i,e,d,c,l,g){return t(),a("div",null,[...e[0]||(e[0]=[s("",60)])])}const u=o(r,[["render",n]]);export{p as __pageData,u as default};
@@ -1,104 +0,0 @@
import{_ as s,o as e,c as a,a2 as i}from"./chunks/framework.BWuWLRhz.js";const g=JSON.parse('{"title":"Multi-Agent Collaboration -- PRD","description":"","frontmatter":{},"headers":[],"relativePath":"archive/prds/multi-agent-collaboration.md","filePath":"archive/prds/multi-agent-collaboration.md","lastUpdated":1785228410000}'),t={name:"archive/prds/multi-agent-collaboration.md"};function o(l,n,p,r,c,d){return e(),a("div",null,[...n[0]||(n[0]=[i(`<h1 id="multi-agent-collaboration-prd" tabindex="-1">Multi-Agent Collaboration -- PRD <a class="header-anchor" href="#multi-agent-collaboration-prd" aria-label="Permalink to &quot;Multi-Agent Collaboration -- PRD&quot;">​</a></h1><p><strong>Status:</strong> Draft (discovery interview complete, 2026-07-25) <strong>Author:</strong> Discovery interview (archie-core-abg.1), synthesized from Sam&#39;s answers <strong>Parent epic:</strong> archie-core-abg</p><hr><h2 id="_0-framing" tabindex="-1">0. Framing <a class="header-anchor" href="#_0-framing" aria-label="Permalink to &quot;0. Framing&quot;">​</a></h2><p>Today, &quot;running multiple agents&quot; means running multiple independent <code>archied</code> processes on the same host (<code>carina</code>): <code>archie</code> (bot_user=archie, multiple repositories, deepseek models) and <code>winter</code> (bot_user=winter, a restricted repository set, local llama.cpp models). Confirmed by diffing <code>~/.config/archie/config.toml</code> and <code>~/.config/archie/winter.toml</code> on carina: they differ in <code>bot_user</code>, <code>[[repos]]</code> list, and <code>[models]</code>/<code>[providers]</code> -- not just identity. <code>Config.BotUser</code> is a single global field, so one process = one identity today.</p><p>The goal stated for archie-core overall is to become a fully extensible agentic workhorse -- comparable to and improving on OpenClaw/Hermes. This PRD scopes the &quot;multi-agent&quot; slice of that: what it takes to go from N processes to one daemon that can do what N processes do, plus the surrounding capabilities (chat channels, plugins, memory) needed to reach that bar.</p><h2 id="_1-scope-confirmed-in-interview" tabindex="-1">1. Scope (confirmed in interview) <a class="header-anchor" href="#_1-scope-confirmed-in-interview" aria-label="Permalink to &quot;1. Scope (confirmed in interview)&quot;">​</a></h2><p>All of the following are <strong>in scope</strong> for the epic (not necessarily the first implementation slice -- see section 6):</p><ol><li><strong>Daemon-side concurrency</strong> -- one daemon process running multiple bot identities concurrently, replacing N separate <code>archied</code> processes.</li><li><strong>Cross-repo / cross-config flexibility</strong> -- identities are not statically bound to one repo list at process startup; repo/model/provider configuration varies per identity within a single daemon.</li><li><strong>Agent-to-agent collaboration on a single task</strong> -- one agent&#39;s output feeding another (e.g. plan -&gt; implement -&gt; review handoff), not just N identities running in parallel unaware of each other.</li><li><strong>Conversational access</strong> -- chat channels (Telegram, web UI, more via plugins) where Sam talks to archie directly, outside the Gitea issue-driven flow. Confirmed requirement: <strong>full parity</strong> with the issue-driven flow -- chat is an alternate entry point into the same triage/planner/builder dispatch pipeline, not a separate toy Q&amp;A surface. Chat must be able to: answer questions read-only, spawn/control real work (start an agent, check status, approve/reject a PR, cancel a run), and drive the same pipeline Gitea assignment drives today.</li><li><strong>General extensibility</strong> -- plugins/channels/integrations should be addable, not hardcoded: <ul><li>Additional forges beyond GitHub/Gitea (e.g. GitLab) via the existing <code>forge.Forge</code> interface, as Layer 2 core plugins (see <code>docs/prds/archie-core-v2-architecture.md</code> sec.5).</li><li>MCP server connections (archie as an MCP client, to consume external tools/data sources).</li><li>SSH / remote execution as an agent capability.</li><li>Arbitrary API integrations, callable by agents as tools.</li><li>Additional chat channels beyond Telegram/web UI, as plugins.</li></ul></li><li><strong>Memory systems for multi-session chat</strong> -- conversations with archie need to persist across sessions (distinct from the existing per-task <code>/data/memory.jsonl</code> sketch in the v2 PRD, which is task/project scoped, not conversation scoped).</li><li><strong>Slash-command capabilities</strong> in chat channels (e.g. <code>/status</code>, <code>/spawn</code>, <code>/approve</code>) for direct channel interaction.</li><li><strong>Multi-user support</strong>, as a capability the architecture should not foreclose -- &quot;if I want to extend my agent to multiple people, I should be able to.&quot; Not required to ship in the first slice (see section 5), bu Line truncated
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[[</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">identities</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">name = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;archie&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">bot_user = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;archie&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">forge = { type = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;gitea&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, host = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, token_env = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">models = { triage = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, planner = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, builder = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">repos = [ </span><span style="--shiki-light:#B31D28;--shiki-light-font-style:italic;--shiki-dark:#FDAEB7;--shiki-dark-font-style:italic;">... </span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[[</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">identities</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">name = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;winter&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">bot_user = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;winter&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">forge = { type = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;gitea&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, host = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, token_env = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">models = { triage = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, planner = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, builder = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">repos = [ </span><span style="--shiki-light:#B31D28;--shiki-light-font-style:italic;--shiki-dark:#FDAEB7;--shiki-dark-font-style:italic;">... </span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span></code></pre></div><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span></span></span>
<span class="line"><span>**Design answer (2026-07-25): per-identity goroutine, shared infrastructure.**</span></span>
<span class="line"><span></span></span>
<span class="line"><span>Each identity gets its own goroutine running an independent poll loop with</span></span>
<span class="line"><span>its own forge client, worktree manager, and NATS subject namespace</span></span>
<span class="line"><span>(\`archie.&lt;identity&gt;.task.&lt;type&gt;\`). They share only the infrastructure</span></span>
<span class="line"><span>pieces where isolation adds cost without benefit:</span></span>
<span class="line"><span></span></span>
<span class="line"><span>| Shared (one instance for all identities) | Per-identity (one per goroutine) |</span></span>
<span class="line"><span>|---|---|</span></span>
<span class="line"><span>| SQLite store (\`internal/store\`) | Forge client (different token per identity) |</span></span>
<span class="line"><span>| NATS connection (\`internal/nats\`) | Worktree manager (different \`BotUser\` per identity) |</span></span>
<span class="line"><span>| Container pool (\`internal/container\`) | Config subset: forge, repos, models, providers, dispatch, poll_interval, bot_user, bot_email |</span></span>
<span class="line"><span>| Event bus (\`internal/events\`) | NATS subject namespace: \`archie.&lt;identity&gt;.task.&lt;type&gt;\` |</span></span>
<span class="line"><span>| Web UI (\`internal/webui\`) | Poll loop goroutine |</span></span>
<span class="line"><span>| Plugin registry (\`internal/plugin\`) | |</span></span>
<span class="line"><span>| Gateway router (\`internal/gateway\`) | |</span></span>
<span class="line"><span></span></span>
<span class="line"><span>Decision rationale: per-identity goroutines guarantee failure isolation (one</span></span>
<span class="line"><span>identity&#39;s forge outage cannot block another&#39;s poll tick), each identity</span></span>
<span class="line"><span>gets its own forge rate-limit domain, and the existing \`Daemon\` struct maps</span></span>
<span class="line"><span>cleanly -- each goroutine holds a thin \`Identity\` value (forge client + config</span></span>
<span class="line"><span>subset + worktree manager + NATS subject prefix) and dispatches tasks with</span></span>
<span class="line"><span>an \`identity_name\` column on the task row. The shared NATS connection</span></span>
<span class="line"><span>multiplexes subjects by identity prefix; the shared store already handles</span></span>
<span class="line"><span>concurrent ClaimNext via SQLite&#39;s serialized writes. NATS subjects carry</span></span>
<span class="line"><span>the identity name so agent containers (which consume from NATS) route</span></span>
<span class="line"><span>responses back to the correct daemon identity.</span></span>
<span class="line"><span></span></span>
<span class="line"><span>This design resolves the open question in section 4 of the original PRD</span></span>
<span class="line"><span>draft (per-identity goroutine vs single loop iterating identities -- the</span></span>
<span class="line"><span>former, for failure isolation).</span></span>
<span class="line"><span></span></span>
<span class="line"><span>## 5. Priority / phasing</span></span>
<span class="line"><span></span></span>
<span class="line"><span>Sam deferred ordering to this PRD (interview answer: &quot;let the interview</span></span>
<span class="line"><span>settle scope, I&#39;ll decide after seeing it written up&quot;). Proposed</span></span>
<span class="line"><span>dependency-ordered phases, for Sam to confirm or reorder:</span></span>
<span class="line"><span></span></span>
<span class="line"><span>**Phase A -- Foundation (blocks everything else)**</span></span>
<span class="line"><span>- Wire Layer 2 core plugin loading (\`~/.config/archie/plugins/\`,</span></span>
<span class="line"><span> \`Plugin.Register(daemon)\`) into \`cmd/archied/main.go\`. Currently designed,</span></span>
<span class="line"><span> unwired -- both chat channels and new forges depend on this existing.</span></span>
<span class="line"><span></span></span>
<span class="line"><span>**Phase B -- Multi-identity daemon core**</span></span>
<span class="line"><span>- Replace single \`Config.BotUser\` with the \`[[identities]]\` shape (section</span></span>
<span class="line"><span> 4, after design confirmation).</span></span>
<span class="line"><span>- Multi-identity poll/dispatch, still issue-driven (Gitea only, no chat yet).</span></span>
<span class="line"><span>- Migrate the two carina processes (archie, winter) onto one daemon as a</span></span>
<span class="line"><span> real-world validation.</span></span>
<span class="line"><span></span></span>
<span class="line"><span>**Phase C -- Chat channel foundation**</span></span>
<span class="line"><span>- Chat channel plugin interface (parallel to \`forge.Forge\`).</span></span>
<span class="line"><span>- Telegram channel plugin: read-only Q&amp;A against task/daemon state first,</span></span>
<span class="line"><span> then spawn/control actions gated through the same review pipeline as</span></span>
<span class="line"><span> issue-driven dispatch.</span></span>
<span class="line"><span>- Web UI: extend \`internal/webui\` from read-only SSE dashboard to</span></span>
<span class="line"><span> bidirectional chat.</span></span>
<span class="line"><span>- Multi-session conversation memory (distinct persistence from per-task</span></span>
<span class="line"><span> \`/data/memory.jsonl\`).</span></span>
<span class="line"><span>- Slash commands (\`/status\`, \`/spawn\`, \`/approve\`, \`/cancel\`).</span></span>
<span class="line"><span></span></span>
<span class="line"><span>**Phase D -- Agent-to-agent collaboration**</span></span>
<span class="line"><span>- Plan -&gt; implement -&gt; review handoff within a single task&#39;s workflow</span></span>
<span class="line"><span> (builds on existing \`workflow.Stage\` sequencing -- this may already be</span></span>
<span class="line"><span> close given the \`implement\` workflow&#39;s plan/build stage split; needs</span></span>
<span class="line"><span> investigation into how much is genuinely new vs. reframing).</span></span>
<span class="line"><span></span></span>
<span class="line"><span>**Phase E -- Extended integrations (as needed, each is an independent</span></span>
<span class="line"><span>plugin, no fixed order)**</span></span>
<span class="line"><span>- GitLab forge plugin.</span></span>
<span class="line"><span>- MCP client capability (archie consuming external MCP servers as tools).</span></span>
<span class="line"><span>- SSH / remote execution tool.</span></span>
<span class="line"><span>- Additional chat channels.</span></span>
<span class="line"><span>- Multi-user support (identity/session model extended beyond</span></span>
<span class="line"><span> single-operator -- needs its own design pass; not blocking Phase A-D).</span></span>
<span class="line"><span></span></span>
<span class="line"><span>Sam&#39;s explicit instruction was to identify next requirements **and begin</span></span>
<span class="line"><span>work**, not just deliver a document. Phase A (wiring the Layer 2 plugin</span></span>
<span class="line"><span>loader) is the correct starting point: it&#39;s small, well-specified already in</span></span>
<span class="line"><span>\`docs/prds/archie-core-v2-architecture.md\` sec.5, and unblocks both the chat</span></span>
<span class="line"><span>channel work and new forge plugins that everything else in this PRD depends</span></span>
<span class="line"><span>on.</span></span>
<span class="line"><span></span></span>
<span class="line"><span>## 6. Acceptance criteria for this PRD</span></span>
<span class="line"><span></span></span>
<span class="line"><span>- [x] Reflects Sam&#39;s actual interview answers, not assumptions.</span></span>
<span class="line"><span>- [x] Confirms the archie/winter config diff (repo lists differ, not just</span></span>
<span class="line"><span> identity).</span></span>
<span class="line"><span>- [ ] Broken into scoped, dependency-ordered beads issues under</span></span>
<span class="line"><span> \`archie-core-abg\`, the way the 5zh epic was. (Next step, this session.)</span></span></code></pre></div>`,19)])])}const u=s(t,[["render",o]]);export{g as __pageData,u as default};
@@ -1 +0,0 @@
import{_ as s,o as e,c as a,a2 as i}from"./chunks/framework.BWuWLRhz.js";const g=JSON.parse('{"title":"Multi-Agent Collaboration -- PRD","description":"","frontmatter":{},"headers":[],"relativePath":"archive/prds/multi-agent-collaboration.md","filePath":"archive/prds/multi-agent-collaboration.md","lastUpdated":1785228410000}'),t={name:"archive/prds/multi-agent-collaboration.md"};function o(l,n,p,r,c,d){return e(),a("div",null,[...n[0]||(n[0]=[i("",19)])])}const u=s(t,[["render",o]]);export{g as __pageData,u as default};
@@ -1,213 +0,0 @@
import{_ as i,o as a,c as n,a2 as t}from"./chunks/framework.BWuWLRhz.js";const g=JSON.parse('{"title":"archie-core TypeScript Plugin Engine -- PRD","description":"","frontmatter":{},"headers":[],"relativePath":"archive/prds/typescript-plugin-engine.md","filePath":"archive/prds/typescript-plugin-engine.md","lastUpdated":1785228410000}'),h={name:"archive/prds/typescript-plugin-engine.md"};function l(e,s,p,k,r,d){return a(),n("div",null,[...s[0]||(s[0]=[t(`<h1 id="archie-core-typescript-plugin-engine-prd" tabindex="-1">archie-core TypeScript Plugin Engine -- PRD <a class="header-anchor" href="#archie-core-typescript-plugin-engine-prd" aria-label="Permalink to &quot;archie-core TypeScript Plugin Engine -- PRD&quot;">​</a></h1><p><strong>Author:</strong> Archie (Hermes agent)<br><strong>Date:</strong> 2026-07-21<br><strong>Status:</strong> Draft</p><hr><h2 id="summary" tabindex="-1">Summary <a class="header-anchor" href="#summary" aria-label="Permalink to &quot;Summary&quot;">​</a></h2><p>A TypeScript-based plugin engine that lets repositories ship interpreted, dynamically-loaded workflow extensions. Plugins are <code>.ts</code> files placed in <code>.archie/workflows/</code>. archie-core discovers them on its next poll cycle, transpiles them to JavaScript via esbuild, and executes them in an embedded <a href="https://github.com/dop251/goja" target="_blank" rel="noreferrer">goja</a> runtime -- a pure-Go ECMAScript interpreter with zero CGO dependencies.</p><hr><h2 id="why-typescript-goja" tabindex="-1">Why TypeScript + goja <a class="header-anchor" href="#why-typescript-goja" aria-label="Permalink to &quot;Why TypeScript + goja&quot;">​</a></h2><h3 id="typescript-as-the-plugin-language" tabindex="-1">TypeScript as the plugin language <a class="header-anchor" href="#typescript-as-the-plugin-language" aria-label="Permalink to &quot;TypeScript as the plugin language&quot;">​</a></h3><p>TypeScript is the most widely understood language among developers writing automation, CI, and workflow scripts. It already ships in most projects. Gate authors already know it. The ecosystem for linting, formatting, and type-checking is mature and free.</p><p>Having a TypeScript-native plugin engine means:</p><ul><li>Plugin authors get familiar syntax, type safety, and IDE support</li><li>No separate toolchain -- just <code>.ts</code> files in a folder</li><li>Skills, gates, and workflow stages share the same language</li></ul><h3 id="why-goja" tabindex="-1">Why goja <a class="header-anchor" href="#why-goja" aria-label="Permalink to &quot;Why goja&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Competitor</th><th>Problem</th></tr></thead><tbody><tr><td>V8 CGO bindings</td><td>Requires CGO, ~50MB static libraries, platform-specific builds</td></tr><tr><td>QuickJS CGO</td><td>Requires CGO, smaller than V8 but still a C dependency</td></tr><tr><td>QJS (Wazero)</td><td>Pure Go WASM, but sandboxed -- can&#39;t expose Go functions efficiently</td></tr><tr><td>Ramune</td><td>Heavy dependency, bundles an entire TypeScript 7 compiler</td></tr><tr><td>Node.js subprocess</td><td>Process overhead per execution, IPC serialization cost</td></tr></tbody></table><p>goja is a pure-Go ECMAScript 5.1+ interpreter at ~20k lines. It:</p><ul><li>Has <strong>zero CGO</strong> -- cross-compiles everywhere Go does</li><li>Passes nearly all TC39 Test262 tests for ES5.1 + significant ES6 coverage</li><li>Can run Babel and the TypeScript compiler itself (proven capability)</li><li>Provides direct Go↔JS interop via <code>Set()</code>/<code>Get()</code>/<code>Runtime.RunString()</code></li><li>Has a companion <code>goja_nodejs</code> package for <code>require()</code>, <code>setTimeout</code>, and <code>console</code></li><li>Is used in production by k6 (Grafana&#39;s load testing tool, 30k+ stars)</li></ul><h3 id="how-typescript-becomes-javascript" tabindex="-1">How TypeScript becomes JavaScript <a class="header-anchor" href="#how-typescript-becomes-javascript" aria-label="Permalink to &quot;How TypeScript becomes JavaScript&quot;">​</a></h3><p>arcie-core bundles esbuild via <code>go:embed</code>. On plugin load, TypeScript source is transpiled to ES2017 JavaScript in-process:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>.archie/workflows/security-gate.ts → esbuild.Transform() → goja.Runtime.RunString()</span></span></code></pre></div><p>esbuild is pure Go, takes ~3ms for typical gate scripts, and strips type annotations without type-checking (the plugin author does that in their editor). If the transpilation fails, the plugin is skipped with a diagnostic comment on the issue.</p><hr><h2 id="design" tabindex="-1">Design <a class="header-anchor" href="#design" aria-label="Permalink to &quot;Design&quot;">​</a></h2><h3 id="plugin-discovery" tabindex="- Line truncated
<span class="line"><span>├── custom-gate.ts # gate functions: exported \`check()\` </span></span>
<span class="line"><span>├── db-migration.ts # custom stage: exported \`stage()\`</span></span>
<span class="line"><span>└── notify-slack.ts # skill script: exported \`run()\`</span></span></code></pre></div><p>Each file is a self-contained module. No <code>package.json</code>, no <code>node_modules</code>, no external imports. If you need external deps, they need to be exposed via archie-core&#39;s Go→JS bridge.</p><h3 id="plugin-types" tabindex="-1">Plugin types <a class="header-anchor" href="#plugin-types" aria-label="Permalink to &quot;Plugin types&quot;">​</a></h3><p>A plugin declares its role via an exported symbol:</p><table tabindex="0"><thead><tr><th>Export</th><th>Role</th><th>When called</th></tr></thead><tbody><tr><td><code>export function check(ctx: GateContext): Finding[]</code></td><td>Gate function</td><td>After shell-based gate, before commit</td></tr><tr><td><code>export function stage(): Stage</code></td><td>Workflow stage</td><td>When a workflow references the stage name</td></tr><tr><td><code>export function run(ctx: ScriptContext): void</code></td><td>Skill script</td><td>When a skill&#39;s instructions invoke the script</td></tr></tbody></table><p>arcie-core discovers the role by checking which exports exist. A file can export multiple roles.</p><h3 id="gate-functions" tabindex="-1">Gate functions <a class="header-anchor" href="#gate-functions" aria-label="Permalink to &quot;Gate functions&quot;">​</a></h3><div class="language-typescript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">typescript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// .archie/workflows/custom-gate.ts</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">interface</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> GateContext</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> diff</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// unified diff of changes</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> changedFiles</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[]; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// list of changed file paths</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> dir</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// absolute worktree path</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> repo</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// &quot;owner/name&quot;</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> baseRef</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// &quot;origin/main&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">interface</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Finding</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> level</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;error&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;warn&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> file</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> line</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> number</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> message</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">interface</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Block</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> name</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> message</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> function</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> check</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> GateContext</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Finding</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[] {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> findings</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Finding</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[] </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [];</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Rule: no new panic() calls</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> for</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> line</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> of</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.diff.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">split</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\n</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)) {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (line.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">startsWith</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;+&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&amp;&amp;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> !</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">line.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">startsWith</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;+++&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)) {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (line.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">includes</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;panic(&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)) {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> findings.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">push</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> level: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;error&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> message: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;new panic() call -- use error returns instead&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Rule: no time.Sleep in non-test files</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> for</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> file</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> of</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.changedFiles) {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (file.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">endsWith</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;_test.go&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">continue</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> content</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> archie.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">readFile</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`\${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ctx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}/\${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">file</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (content.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">includes</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;time.Sleep&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)) {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> findings.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">push</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> level: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;warn&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> file: file,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> message: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;time.Sleep in non-test code -- use time.Ticker instead&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> findings;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>After transpilation and execution, archie-core calls <code>check(ctx)</code> via goja. Error-level findings park the task. Warn-level findings are logged.</p><h3 id="custom-workflow-stages" tabindex="-1">Custom workflow stages <a class="header-anchor" href="#custom-workflow-stages" aria-label="Permalink to &quot;Custom workflow stages&quot;">​</a></h3><div class="language-typescript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">typescript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// .archie/workflows/run-migrations.ts</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> function</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> stage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">()</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Stage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> name: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;db-migration&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> TaskContext</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Check if migrations directory exists</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> hasMigrations</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> archie.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">fileExists</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`\${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ctx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}/migrations\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">hasMigrations) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// nothing to do</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Run migration tests</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> result</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> archie.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">exec</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;go&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;test&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;./migrations/...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]);</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (result.exitCode </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!==</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 0</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> \`migration tests failed: \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">result</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">stderr</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// success</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> };</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="skill-scripts" tabindex="-1">Skill scripts <a class="header-anchor" href="#skill-scripts" aria-label="Permalink to &quot;Skill scripts&quot;">​</a></h3><div class="language-typescript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">typescript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// .archie/workflows/security-audit.ts</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> function</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> ScriptContext</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> void</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> result</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> archie.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">exec</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;gitleaks&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;detect&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;--no-git&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]);</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (result.exitCode </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!==</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 0</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> archie.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">log</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;warn&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`gitleaks found secrets:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\n</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">result</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">stdout</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> archie.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">log</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;info&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;security audit complete&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="archie-go→js-bridge" tabindex="-1">archie Go→JS bridge <a class="header-anchor" href="#archie-go→js-bridge" aria-label="Permalink to &quot;archie Go→JS bridge&quot;">​</a></h3><p>arcie-core exposes a <code>archie</code> global in the goja runtime:</p><div class="language-typescript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">typescript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">interface</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Archie</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // File operations (scoped to worktree)</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> readFile</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">path</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> fileExists</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">path</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> boolean</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> listDir</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">path</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[];</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> walkDir</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">path</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[];</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> </span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Shell execution</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> exec</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">command</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">args</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[])</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> ExecResult</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> </span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Logging</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> log</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">level</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">message</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> void</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> </span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Path utilities</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> resolve</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">...</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">parts</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[])</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> ext</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">path</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> </span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Environment</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> env</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">key</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> </span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // HTTP (optional, gated)</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> fetch</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">url</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">options</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> FetchOptions</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> FetchResult</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">interface</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> ExecResult</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> stdout</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> stderr</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> exitCode</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> number</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>All file operations are <strong>jailed to the worktree</strong>. <code>archie.readFile(&quot;/etc/passwd&quot;)</code> fails. The bridge enforces this in Go before passing the path to the OS.</p><h3 id="reload-cycle" tabindex="-1">Reload cycle <a class="header-anchor" href="#reload-cycle" aria-label="Permalink to &quot;Reload cycle&quot;">​</a></h3><p>Plugins are loaded fresh on every poll cycle -- archie-core already fresh-clones per task. No hot-reload complexity, no cache invalidation. The worktree is the source of truth.</p><p>For the rare case where a plugin errors at parse/transpile time, archie-core comments on the issue with the diagnostic and parks the task. The plugin author fixes the <code>.ts</code> file and requeues.</p><hr><h2 id="implementation" tabindex="-1">Implementation <a class="header-anchor" href="#implementation" aria-label="Permalink to &quot;Implementation&quot;">​</a></h2><h3 id="architecture" tabindex="-1">Architecture <a class="header-anchor" href="#architecture" aria-label="Permalink to &quot;Architecture&quot;">​</a></h3><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>internal/plugins/</span></span>
<span class="line"><span>├── loader.go # scan .archie/workflows/, transpile, evaluate</span></span>
<span class="line"><span>├── runtime.go # goja runtime pool management</span></span>
<span class="line"><span>├── bridge.go # archie global (file I/O, exec, log, fetch)</span></span>
<span class="line"><span>├── types.go # GateContext, Finding, Stage, TaskContext → JS types</span></span>
<span class="line"><span>├── loader_test.go</span></span>
<span class="line"><span>└── testdata/</span></span>
<span class="line"><span> └── workflows/</span></span>
<span class="line"><span> ├── gate.ts # test gate plugin</span></span>
<span class="line"><span> └── stage.ts # test stage plugin</span></span></code></pre></div><h3 id="goja-runtime-pool" tabindex="-1">goja runtime pool <a class="header-anchor" href="#goja-runtime-pool" aria-label="Permalink to &quot;goja runtime pool&quot;">​</a></h3><p>Workflow stages and gates need a clean goja runtime per execution. Creating a new runtime per call is slow (~50ms for stdlib setup). A pool of pre-warmed runtimes solves this:</p><div class="language-go vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">go</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">type</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Pool</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> struct</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> warm </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">chan</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> *</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">goja</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Runtime</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">func</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> NewPool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">size</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> int</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">*</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Pool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> p </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &amp;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Pool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{warm: </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">make</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">chan</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> *</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">goja</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Runtime</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, size)}</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> for</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> i </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 0</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; i </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> size; i</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">++</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> rt </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> goja.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">New</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">()</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> installBridge</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(rt) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// register the \`archie\` global</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> installStdlib</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(rt) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// console, setTimeout, etc.</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> p.warm </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> rt</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> p</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">func</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">p </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">*</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Pool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> context</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Context</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">src</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">globals</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> map</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">any</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) (</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">goja</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Value</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">error</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> rt </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">p.warm</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> defer</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> func</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() { p.warm </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> rt }()</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Set per-execution globals</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> for</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> k, v </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> range</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> globals {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> rt.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Set</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(k, v)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> rt.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">RunString</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(src)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="transpile-pipeline" tabindex="-1">Transpile pipeline <a class="header-anchor" href="#transpile-pipeline" aria-label="Permalink to &quot;Transpile pipeline&quot;">​</a></h3><div class="language-go vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">go</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">func</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">l </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">*</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Loader</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">transpile</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">filename</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ts</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> []</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">byte</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) (</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">error</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> result </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> l.esbuild.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Transform</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(ts), </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">api</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">TransformOptions</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Loader: api.LoaderTS,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Target: api.ES2017,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Sourcefile: filename,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> })</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> len</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(result.Errors) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 0</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, fmt.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Errorf</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;transpile </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">%s</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">%v</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, filename, result.Errors)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(result.Code), </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">nil</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="load-pipeline" tabindex="-1">load pipeline <a class="header-anchor" href="#load-pipeline" aria-label="Permalink to &quot;load pipeline&quot;">​</a></h3><div class="language-go vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">go</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">func</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">l </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">*</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Loader</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">LoadPlugins</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">worktreeDir</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) ([]</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Plugin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">error</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> filepath.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Join</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(worktreeDir, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;.archie&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;workflows&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> entries, err </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> os.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">ReadDir</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(dir)</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> os.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">IsNotExist</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(err) {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">nil</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // no plugins -- not an error</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> err </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, err</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> var</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> plugins []</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Plugin</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> for</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> _, e </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> range</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> entries {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> !</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">strings.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">HasSuffix</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(e.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(), </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;.ts&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> continue</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> path </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> filepath.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Join</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(dir, e.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">())</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> src, err </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> os.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">ReadFile</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(path)</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> err </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> continue</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> js, err </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> l.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">transpile</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(e.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(), src)</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> err </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> l.log.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Warn</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;plugin transpile failed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;file&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, e.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(), </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;err&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, err)</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> continue</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> rt </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> l.pool.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Acquire</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">()</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> _, err </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> rt.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">RunString</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(js)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> l.pool.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Release</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(rt)</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> err </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> l.log.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Warn</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;plugin eval failed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;file&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, e.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(), </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;err&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, err)</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> continue</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> plugins </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> append</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(plugins, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">discover</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(rt, e.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">())</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">...</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> plugins, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">nil</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="export-discovery" tabindex="-1">Export discovery <a class="header-anchor" href="#export-discovery" aria-label="Permalink to &quot;Export discovery&quot;">​</a></h3><div class="language-go vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">go</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">func</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> discover</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">rt</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> *</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">goja</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Runtime</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">filename</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) []</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Plugin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> var</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> out []</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Plugin</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> check </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> rt.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Get</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;check&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">); check </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> out </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> append</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(out, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Plugin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{Kind: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;gate&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, Name: filename, Func: check})</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> stage </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> rt.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Get</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;stage&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">); stage </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> out </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> append</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(out, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Plugin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{Kind: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;stage&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, Name: filename, Func: stage})</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> run </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> rt.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Get</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;run&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">); run </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> out </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> append</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(out, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Plugin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{Kind: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;script&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, Name: filename, Func: run})</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> out</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="wiring-into-the-daemon" tabindex="-1">Wiring into the daemon <a class="header-anchor" href="#wiring-into-the-daemon" aria-label="Permalink to &quot;Wiring into the daemon&quot;">​</a></h3><p>In <code>daemon.process()</code>:</p><div class="language-go vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">go</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// After worktree prepare, before gate stage:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">plugins, err </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> d.Plugins.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">LoadPlugins</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(tc.Dir)</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> err </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> d.Log.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Warn</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;plugin load failed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;err&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, err)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">tc.Plugins </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> plugins </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// available to all stages via TaskContext</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// In the gate stage:</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> gatePlugin </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> tc.Plugins.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Gate</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(); gatePlugin </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> findings </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> callGatePlugin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(gatePlugin, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">gateContext</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(tc))</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> for</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> _, f </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> range</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> findings {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> f.Level </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">==</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;error&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // park the task</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><hr><h2 id="limitations" tabindex="-1">Limitations <a class="header-anchor" href="#limitations" aria-label="Permalink to &quot;Limitations&quot;">​</a></h2><h3 id="goja-s-ecmascript-coverage" tabindex="-1">goja&#39;s ECMAScript coverage <a class="header-anchor" href="#goja-s-ecmascript-coverage" aria-label="Permalink to &quot;goja&#39;s ECMAScript coverage&quot;">​</a></h3><p>goja natively supports ES5.1 with significant ES6 features. Modern syntax like <code>async/await</code>, <code>??</code>, <code>?.</code>, or <code>class</code> fields may not parse. The transpile step (esbuild targeting ES2017) handles most of this, but there will be edge cases:</p><table tabindex="0"><thead><tr><th>Feature</th><th>Status</th></tr></thead><tbody><tr><td>Arrow functions</td><td>✅ via transpile</td></tr><tr><td>Template literals</td><td>✅ via transpile</td></tr><tr><td>Destructuring</td><td>✅ via transpile</td></tr><tr><td><code>const</code>/<code>let</code></td><td>✅ via transpile</td></tr><tr><td><code>async/await</code></td><td>❌ not supported (goja is synchronous)</td></tr><tr><td><code>Promise</code></td><td>❌ requires <code>goja_nodejs</code> event loop</td></tr><tr><td>Generators</td><td>❌ not supported</td></tr><tr><td><code>Proxy</code></td><td>❌ not supported</td></tr></tbody></table><p>For gate scripts, this is fine -- gates are synchronous by nature. If async is genuinely needed later, the Bun backend (via <code>tsgo</code>) is the escape hatch.</p><h3 id="performance" tabindex="-1">Performance <a class="header-anchor" href="#performance" aria-label="Permalink to &quot;Performance&quot;">​</a></h3><p>Gate scripts run once per task. Even a 100ms transpile+eval overhead is negligible compared to the LLM calls in the workflow. If a plugin becomes hot-path, it should be promoted to a compiled Go stage.</p><h3 id="no-external-imports" tabindex="-1">No external imports <a class="header-anchor" href="#no-external-imports" aria-label="Permalink to &quot;No external imports&quot;">​</a></h3><p>Plugins can&#39;t <code>import</code> from npm or other files. They&#39;re self-contained modules. Complexity that needs external deps should be a compiled Go stage, not a plugin. The <code>archie</code> global provides filesystem and shell access, which covers the common cases.</p><hr><h2 id="comparison-yaegi-vs-goja" tabindex="-1">Comparison: Yaegi vs goja <a class="header-anchor" href="#comparison-yaegi-vs-goja" aria-label="Permalink to &quot;Comparison: Yaegi vs goja&quot;">​</a></h2><table tabindex="0"><thead><tr><th></th><th>Yaegi (Go)</th><th>goja + esbuild (TypeScript)</th></tr></thead><tbody><tr><td><strong>Language</strong></td><td>Go</td><td>TypeScript</td></tr><tr><td><strong>Pure Go</strong></td><td>✅</td><td>✅ (goja + esbuild both pure Go)</td></tr><tr><td><strong>CGO</strong></td><td>None</td><td>None</td></tr><tr><td><strong>Transpile step</strong></td><td>None (interpreted directly)</td><td>esbuild TS→JS (~3ms)</td></tr><tr><td><strong>Author audience</strong></td><td>Go developers</td><td>Anyone who knows TypeScript</td></tr><tr><td><strong>Type annotations</strong></td><td>N/A (Go is typed)</td><td>Stripped by esbuild (no type-check at runtime)</td></tr><tr><td><strong>Interop</strong></td><td>Direct Go↔Go via <code>Use()</code></td><td>Bridge via <code>archie</code> global</td></tr><tr><td><strong>Performance</strong></td><td>Interpreted Go (~10x slower than compiled)</td><td>Interpreted JS (~50x slower than V8, fine for gates)</td></tr><tr><td><strong>Maturity</strong></td><td>8k stars, used by Traefik for plugins</td><td>7k stars, used by k6, goja is battle-tested</td></tr><tr><td><strong>File extension</strong></td><td><code>.go</code></td><td><code>.ts</code></td></tr><tr><td><strong>Plugin folder</strong></td><td><code>.archie/workflows/</code></td><td><code>.archie/workflows/</code></td></tr><tr><td><strong>Best for</strong></td><td>Custom stages needing Go&#39;s stdlib, tight daemon integration</td><td>Custom gates and scripts where author familiarity matters</td></tr></tbody></table><p><strong>Recommendation: support both.</strong> They solve different problems. Yaegi for repo owners who want full Go power in their custom stages. goja for repo owners who want to write gates and scripts in TypeScript. Both load from <code>.archie/workflows/</code> -- archie-core discovers which engine to use by file extension (<code>.go</code> → Yaegi, <code>.ts</code> → goja+esbuild).</p><hr><h2 id="implementation-phases" tabindex="-1">Implementation phases <a class="header-anchor" href="#implementation-phases" aria-label="Permalink to &quot;Implementation phases&quot;">​</a></h2><h3 id="phase-1-goja-runtime-esbuild" tabindex="-1">Phase 1: goja runtime + esbuild <a class="header-anchor" href="#phase-1-goja-runtime-esbuild" aria-label="Permalink to &quot;Phase 1: goja Line truncated
@@ -1 +0,0 @@
import{_ as i,o as a,c as n,a2 as t}from"./chunks/framework.BWuWLRhz.js";const g=JSON.parse('{"title":"archie-core TypeScript Plugin Engine -- PRD","description":"","frontmatter":{},"headers":[],"relativePath":"archive/prds/typescript-plugin-engine.md","filePath":"archive/prds/typescript-plugin-engine.md","lastUpdated":1785228410000}'),h={name:"archive/prds/typescript-plugin-engine.md"};function l(e,s,p,k,r,d){return a(),n("div",null,[...s[0]||(s[0]=[t("",86)])])}const o=i(h,[["render",l]]);export{g as __pageData,o as default};
@@ -1,102 +0,0 @@
import{_ as i,o as a,c as e,a2 as t}from"./chunks/framework.BWuWLRhz.js";const c=JSON.parse('{"title":"archie-core Yaegi Plugin System -- PRD","description":"","frontmatter":{},"headers":[],"relativePath":"archive/prds/yaegi-plugin-system.md","filePath":"archive/prds/yaegi-plugin-system.md","lastUpdated":1785228410000}'),n={name:"archive/prds/yaegi-plugin-system.md"};function l(h,s,p,r,o,k){return a(),e("div",null,[...s[0]||(s[0]=[t(`<h1 id="archie-core-yaegi-plugin-system-prd" tabindex="-1">archie-core Yaegi Plugin System -- PRD <a class="header-anchor" href="#archie-core-yaegi-plugin-system-prd" aria-label="Permalink to &quot;archie-core Yaegi Plugin System -- PRD&quot;">​</a></h1><p><strong>Author:</strong> Archie (Hermes agent)<br><strong>Date:</strong> 2026-07-21<br><strong>Status:</strong> Draft</p><hr><h2 id="summary" tabindex="-1">Summary <a class="header-anchor" href="#summary" aria-label="Permalink to &quot;Summary&quot;">​</a></h2><p>Embed the <a href="https://github.com/traefik/yaegi" target="_blank" rel="noreferrer">Yaegi</a> Go interpreter to let archie-core load and execute <code>.go</code> files at runtime. This enables three things that shell commands can&#39;t do: <strong>custom gates with deep worktree inspection</strong>, <strong>custom workflow stages defined per-repo</strong>, and <strong>skill scripts written in Go instead of shell</strong>.</p><hr><h2 id="why-yaegi" tabindex="-1">Why Yaegi <a class="header-anchor" href="#why-yaegi" aria-label="Permalink to &quot;Why Yaegi&quot;">​</a></h2><h3 id="the-problem-with-shell-only-gates" tabindex="-1">The problem with shell-only gates <a class="header-anchor" href="#the-problem-with-shell-only-gates" aria-label="Permalink to &quot;The problem with shell-only gates&quot;">​</a></h3><p><code>[[repos.gate]]</code> is command lists. That&#39;s fine for standard tooling (<code>go vet</code>, <code>golangci-lint</code>), but it can&#39;t express project-specific rules:</p><ul><li>&quot;No new <code>panic()</code> calls in the diff&quot;</li><li>&quot;No new dependencies in <code>go.mod</code> without justification&quot;</li><li>&quot;All public functions in <code>pkg/api/</code> must be documented&quot;</li><li>&quot;No <code>time.Sleep</code> in production code paths&quot;</li></ul><p>These are rules that need to read the diff, parse Go ASTs, or walk the worktree -- things shell scripts can do but shouldn&#39;t have to.</p><h3 id="why-not-shell-scripts" tabindex="-1">Why not shell scripts? <a class="header-anchor" href="#why-not-shell-scripts" aria-label="Permalink to &quot;Why not shell scripts?&quot;">​</a></h3><p>Shell scripts for gates are fine until they&#39;re not. They can&#39;t import the archie-core types, can&#39;t use the Go parser, and are a second language to maintain alongside the daemon. Yaegi runs Go -- the same language as the daemon, the same language as the repos archie-core works on.</p><h3 id="why-not-go-s-native-plugin-package" tabindex="-1">Why not Go&#39;s native <code>plugin</code> package? <a class="header-anchor" href="#why-not-go-s-native-plugin-package" aria-label="Permalink to &quot;Why not Go&#39;s native \`plugin\` package?&quot;">​</a></h3><p>Go&#39;s <code>plugin</code> package (<code>.so</code> files) requires:</p><ul><li>Exact same Go version and deps as the host binary</li><li>Linux/macOS only</li><li>No unload</li><li>Painful distribution</li></ul><p>Yaegi interprets <code>.go</code> source files directly -- no compilation step, portable everywhere, loads from filesystem paths.</p><h3 id="production-precedent" tabindex="-1">Production precedent <a class="header-anchor" href="#production-precedent" aria-label="Permalink to &quot;Production precedent&quot;">​</a></h3><ul><li><strong>Traefik:</strong> 200+ community plugins via Yaegi, loaded from plugins.traefik.io</li><li><strong>Vikunja:</strong> Adopted Yaegi for plugin system (see PR #2178), loads plugins from <code>plugins/</code> directory</li></ul><hr><h2 id="design" tabindex="-1">Design <a class="header-anchor" href="#design" aria-label="Permalink to &quot;Design&quot;">​</a></h2><h3 id="three-extension-surfaces" tabindex="-1">Three extension surfaces <a class="header-anchor" href="#three-extension-surfaces" aria-label="Permalink to &quot;Three extension surfaces&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Surface</th><th>Location</th><th>When loaded</th><th>What it does</th></tr></thead><tbody><tr><td><strong>Custom gate functions</strong></td><td><code>.archie/gate.go</code></td><td>During the gate stage (after shell commands)</td><td>Returns <code>[]Finding</code> -- each finding has severity, message, file, line</td></tr><tr><td><strong>Custom workflow stages</strong></td><td><code>.archie/stages/&lt;name&gt;.go</code></td><td>When the workflow references the stage name</td><td>Returns a <code>workflow.Stage</code> implementation</td></tr><tr><td><strong>Skill scripts</strong></td><td><code>.archie/skills/&lt;skill&gt;/scr Line truncated
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">package</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> gate</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">fmt</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">os</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">path/filepath</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">strings</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// GateContext carries everything the gate checker can inspect.</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">type</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> GateContext</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> struct</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Diff </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // unified diff of all changes</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ChangedFiles []</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // list of changed file paths (repo-relative)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // absolute worktree path</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> BaseRef </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // base branch (e.g. &quot;origin/main&quot;)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Repo </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // &quot;owner/name&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Finding is one gate violation.</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">type</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Finding</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> struct</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Level </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // &quot;error&quot; (blocks commit) or &quot;warn&quot; (advisory)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> File </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // optional file path</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Line </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">int</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // optional line number</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Message </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Block defines a named rule that can prevent passing.</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">type</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Block</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> struct</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Name </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Message </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Check returns findings for the gate. Return nil for a clean gate.</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">func</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Check</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> GateContext</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) []</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Finding</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> var</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> findings []</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Finding</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Rule: no new panic() calls in committed code</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> for</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> _, line </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> range</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> strings.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Split</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(ctx.Diff, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\n</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> strings.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">HasPrefix</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(line, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;+&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&amp;&amp;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> !</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">strings.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">HasPrefix</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(line, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;+++&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> strings.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Contains</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(line, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;panic(&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> findings </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> append</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(findings, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Finding</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Level: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;error&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Message: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;new panic() call -- use error returns instead&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> })</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Rule: no time.Sleep in non-test files</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> for</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> _, f </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> range</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.ChangedFiles {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> strings.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">HasSuffix</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(f, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;_test.go&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> continue</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> path </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> filepath.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Join</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(ctx.Dir, f)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> b, err </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> os.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">ReadFile</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(path)</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> err </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> continue</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> strings.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Contains</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(b), </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;time.Sleep&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> findings </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> append</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(findings, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Finding</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Level: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;warn&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> File: f,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Message: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;time.Sleep in non-test code -- use time.Ticker or context.WithTimeout instead&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> })</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> findings</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>The daemon:</p><ol><li>Reads <code>.archie/gate.go</code> from the worktree</li><li>Creates a Yaegi interpreter with <code>GateContext</code> and <code>Finding</code> types pre-loaded via <code>Use()</code></li><li>Evaluates the file</li><li>Calls <code>Check(ctx)</code> via <code>Eval(&quot;gate.Check&quot;)</code> + <code>Interface()</code></li><li>Logs findings and blocks the gate if any have <code>Level: &quot;error&quot;</code></li></ol><h3 id="custom-workflow-stages-archie-stages" tabindex="-1">Custom workflow stages (<code>.archie/stages/</code>) <a class="header-anchor" href="#custom-workflow-stages-archie-stages" aria-label="Permalink to &quot;Custom workflow stages (\`.archie/stages/\`)&quot;">​</a></h3><p>A repo can define custom pipeline stages that archie-core discovers and makes routable:</p><div class="language-go vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">go</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// .archie/stages/run-migrations.go</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">package</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> stages</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">github.com/samcharles93/archie-core/internal/workflow</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">func</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Stage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">workflow</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Stage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> workflow</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Stage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Name: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;db-migration&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Run: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">func</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> context</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Context</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">tc</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> *</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">workflow</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">TaskContext</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">error</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Check if go.mod contains migration tools</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Run migration tests</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Verify schema compatibility</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Registered stages appear alongside built-in stages. A workflow in <code>config.toml</code> can reference them by name:</p><div class="language-toml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">toml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[[</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">workflows</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">stages</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]]</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">name = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;db-migration&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # matches the .go file</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">source = </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;repo&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # loaded from .archie/stages/</span></span></code></pre></div><h3 id="skill-scripts-archie-skills-skill-scripts" tabindex="-1">Skill scripts (<code>.archie/skills/&lt;skill&gt;/scripts/</code>) <a class="header-anchor" href="#skill-scripts-archie-skills-skill-scripts" aria-label="Permalink to &quot;Skill scripts (\`.archie/skills/&lt;skill&gt;/scripts/\`)&quot;">​</a></h3><p>Skills can ship Go scripts that archie-core interprets:</p><div class="language-go vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">go</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// .archie/skills/security-audit/scripts/gitleaks.go</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">package</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> main</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">fmt</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">os/exec</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">context</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">func</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> main</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> context.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Background</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">()</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> cmd </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> exec.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">CommandContext</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(ctx, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;gitleaks&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;detect&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;--no-git&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;--verbose&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> out, _ </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> cmd.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">CombinedOutput</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">()</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> fmt.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Println</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(out))</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Skills reference these scripts naturally in their instructions: &quot;Run <code>scripts/gitleaks.go</code> to scan for secrets.&quot;</p><hr><h2 id="api-surface-archie-core-exposes-to-yaegi" tabindex="-1">API surface archie-core exposes to Yaegi <a class="header-anchor" href="#api-surface-archie-core-exposes-to-yaegi" aria-label="Permalink to &quot;API surface archie-core exposes to Yaegi&quot;">​</a></h2><p>Via <code>i.Use()</code>, the daemon pre-loads symbols that interpreted code can import:</p><table tabindex="0"><thead><tr><th>Package</th><th>What&#39;s exposed</th></tr></thead><tbody><tr><td><code>archie-core/internal/workflow</code></td><td><code>Stage</code>, <code>TaskContext</code>, <code>Outcome</code></td></tr><tr><td><code>archie-core/internal/gate</code></td><td><code>GateContext</code>, <code>Finding</code>, <code>Block</code></td></tr><tr><td><code>stdlib</code></td><td>Full Go standard library (stdlib.Symbols)</td></tr></tbody></table><p>Generated with <code>yaegi extract</code> -- same approach Traefik and Vikunja use. A <code>//go:generate yaegi extract ...</code> line in the source triggers symbol table generation during <code>go generate</code>.</p><hr><h2 id="limitations" tabindex="-1">Limitations <a class="header-anchor" href="#limitations" aria-label="Permalink to &quot;Limitations&quot;">​</a></h2><p>From Yaegi&#39;s own docs:</p><ul><li><strong>No assembly files</strong> (<code>.s</code> not supported)</li><li><strong>No CGo</strong> (can&#39;t call C code -- the daemon is pure Go, so this doesn&#39;t matter)</li><li><strong>No compiler/linker directives</strong> (no <code>//go:embed</code>, etc. -- fine for gate scripts)</li><li><strong>Interfaces from pre-compiled code can&#39;t be added dynamically</strong> -- the daemon must pre-compile wrapper types for any interface interpreted code needs to implement</li><li><strong>Slower than compiled code</strong> -- gate scripts run once per commit, not in hot paths; negligible impact</li></ul><p>The Vikunja PR documents a specific Yaegi quirk: <strong>typed factory functions required.</strong> You can&#39;t do <code>v.Interface().(MyInterface)</code> on a value returned from interpreted code. Each interface needs its own factory:</p><div class="language-go vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">go</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">func</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> NewGate</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Gate</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">return</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &amp;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">MyGate</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{} }</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">func</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> NewReportable</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Reportable</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">return</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &amp;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">MyGate</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{} }</span></span></code></pre></div><hr><h2 id="implementation-phases" tabindex="-1">Implementation phases <a class="header-anchor" href="#implementation-phases" aria-label="Permalink to &quot;Implementation phases&quot;">​</a></h2><h3 id="phase-1-gate-functions-implemented" tabindex="-1">Phase 1: Gate functions -- implemented <a class="header-anchor" href="#phase-1-gate-functions-implemented" aria-label="Permalink to &quot;Phase 1: Gate functions -- implemented&quot;">​</a></h3><ul><li><code>yaegi</code> added as a dependency</li><li>Symbol table for <code>GateContext</code>, <code>Finding</code> generated via <code>yaegi extract</code> into <code>internal/gate/gateextract</code> (a separate package from <code>internal/gate</code> itself, avoiding the self-import cycle extracting a package&#39;s own symbols creates)</li><li><code>internal/gate/gateeval.Evaluate</code>: loads <code>.archie/gate.go</code> from the worktree, interprets it, calls <code>Check()</code>; panics are recovered</li><li>Wired in as <code>workflow.StageYaegiGate</code>, run after the final commit in both the <code>implement</code> and <code>tdd</code> workflows</li><li>Error findings park the task; warn findings are logged only</li></ul><h3 id="phase-2-custom-stages-implemented" tabindex="-1">Phase 2: Custom stages -- implemented <a class="header-anchor" href="#phase-2-custom-stages-implemented" aria-label="Permalink to &quot;Phase 2: Custom stages -- implemented&quot;">​</a></h3><ul><li>Symbol table for <code>workflow.Stage</code>/<code>TaskContext</code>/<code>Outcome</code> generated into <code>internal/workflow/wfextract</code></li><li><code>internal/workflow/wfeval.Discover</code> scans <code>.archie/stages/*.go</code> in filename order and calls each file&#39;s exported <code>Stage()</code> function</li><li><code>TaskContext.CustomStages</code> is an injected <code>func(dir string) ([]Stage, error)</code> -- the composition root (<code>cmd/archied</code>) wires it to <code>wfeval.Discover</code>, keeping <code>internal/workflow</code> decoupled from its own generated symbol table</li><li><code>workflow.StageRepoStages</code> runs discovered stages in order right after the worktree is prepared, in both <code>implement</code> and <code>tdd</code></li><li>Simplification vs. the original sketch: stages are auto-discovered and always run (like <code>.archie/gate.go</code>) rather than referenced by name from <code>config.toml</code> -- the workflow engine has no data-driven stage graph today, so wiring arbitrary named stages into arbitrary positions would need a larger config-driven rework. Auto-run-in-order covers the PRD&#39;s actual use case (a repo-defined pre-flight/setup hook) without it.</li></ul><h3 id="phase-3-skill-scripts-implemented" tabindex="-1">Phase 3: Skill scripts -- implemented <a class="header-anchor" href="#phase-3-skill-scripts-implemented" aria-label="Permalink to &quot;Phase 3: Skill scripts -- implemented&quot;">​</a></h3><ul><li><code>internal/skillscript.Run</code> interprets a <code>.go</code> file via <code>i.EvalPath</code>, which (like <code>go run</code>) evaluates and calls its <code>main()</code>; stdout/stderr are captured via <code>interp.Options</code></li><li>Uses <code>stdlib.Symbols</code> + <code>stdlib/unrestricted.Symbols</code> (not just <code>stdlib</code>) -- <code>os/exec</code> lives in the unrestricted set, and the PRD&#39;s own example script shells out via <code>os/exec</code></li><li>No archie-core-specific symbol table needed here -- skill scripts only touch the Go standard library</li><li>Exposed to the agent loop as a new <code>run_go_script</code> tool (<code>internal/agentexec/inprocess.go</code>), available in every agent stage; path is validated to stay inside the workspace</li><li>This is how &quot;the skill&#39;s instructions reference a script&quot; cashes out concretely: the agent calls <code>run_go_script</code> with the path instead of needing a Go toolchain in the sandbox</li></ul><h3 id="phase-4-hot-reload-not-needed-by-construction" tabindex="-1">Phase 4: Hot reload -- not needed, by construction <a class="header-anchor" href="#phase-4-hot-reload-not-needed-by-construction" aria-label="Permalink to &quot;Phase 4: Hot reload -- not needed, by construction&quot;">​</a></h3><ul><li>All three loaders (<code>gate.Evaluate</Line truncated
@@ -1 +0,0 @@
import{_ as i,o as a,c as e,a2 as t}from"./chunks/framework.BWuWLRhz.js";const c=JSON.parse('{"title":"archie-core Yaegi Plugin System -- PRD","description":"","frontmatter":{},"headers":[],"relativePath":"archive/prds/yaegi-plugin-system.md","filePath":"archive/prds/yaegi-plugin-system.md","lastUpdated":1785228410000}'),n={name:"archive/prds/yaegi-plugin-system.md"};function l(h,s,p,r,o,k){return a(),e("div",null,[...s[0]||(s[0]=[t("",61)])])}const g=i(n,[["render",l]]);export{c as __pageData,g as default};
@@ -1 +0,0 @@
const e='{"documentCount":296,"nextId":296,"documentIds":{"0":"/architecture/agent-system#agent-system","1":"/architecture/agent-system#domain-framing","2":"/architecture/agent-system#canonical-agent-interaction-model","3":"/architecture/agent-system#workflow-execution-identity","4":"/architecture/agent-system#memory-scopes","5":"/architecture/agent-system#agent-and-workflow-domain-boundary","6":"/architecture/agent-system#canonical-workflow-model","7":"/architecture/agent-system#current-workflow-execution-feature","8":"/architecture/agent-system#current-workflow-feature-placement","9":"/architecture/agent-system#current-task-meanings-and-required-replacements","10":"/architecture/agent-system#terms-that-do-not-migrate","11":"/architecture/agent-system#current-workflowexecution-data-inventory","12":"/architecture/agent-system#current-runtime-responsibilities-to-unify","13":"/architecture/agent-system#current-workflow-feature-hazards","14":"/architecture/agent-system#existing-invariants-to-preserve","15":"/architecture/agent-system#required-migration","16":"/architecture/dependencies-and-contracts#dependencies-and-contracts","17":"/architecture/dependencies-and-contracts#dependency-direction","18":"/architecture/dependencies-and-contracts#commands-and-events","19":"/architecture/dependencies-and-contracts#event-bus","20":"/architecture/dependencies-and-contracts#wire-contracts-and-generation","21":"/architecture/configuration#configuration","22":"/architecture/configuration#ownership","23":"/architecture/configuration#private-input-document","24":"/architecture/configuration#dissolution-of-internal-config","25":"/architecture/configuration#repository-settings","26":"/architecture/configuration#documentation","27":"/architecture/configuration#value-classification-rule","28":"/architecture/configuration#current-configuration-migration-ledger","29":"/architecture/configuration#behavioural-literals-and-incorrectly-fixed-values","30":"/architecture/configuration#constants-that-may-remain","31":"/architecture/configuration#current-mutation-and-reload-ledger","32":"/architecture/configuration#universal-change-protocol","33":"/architecture/configuration#completion-criteria","34":"/architecture/generated-documentation#generated-documentation-and-documentation-site","35":"/architecture/generated-documentation#purpose","36":"/architecture/generated-documentation#vitepress-site","37":"/architecture/generated-documentation#github-pages-workflow","38":"/architecture/generated-documentation#single-source-of-truth","39":"/architecture/generated-documentation#target-generation-architecture","40":"/architecture/generated-documentation#target-output","41":"/architecture/generated-documentation#generation-steps","42":"/architecture/generated-documentation#step-1-maintain-the-archie-tools-module","43":"/architecture/generated-documentation#step-2-establish-authoritative-registries","44":"/architecture/generated-documentation#step-3-generate-asyncapi","45":"/architecture/generated-documentation#step-4-add-generated-documentation-data","46":"/architecture/generated-documentation#step-5-render-data-with-vitepress","47":"/architecture/generated-documentation#step-6-implement-deterministic-drift-checking","48":"/architecture/generated-documentation#step-7-adapt-the-vitepress-site","49":"/architecture/generated-documentation#step-8-adapt-developer-commands","50":"/architecture/generated-documentation#step-9-adapt-ci-and-pages-deployment","51":"/architecture/generated-documentation#step-10-remove-non-source-artifacts-and-cut-over","52":"/architecture/generated-documentation#hook-and-ci-policy","53":"/architecture/generated-documentation#validation-requirements","54":"/architecture/generated-documentation#completion-criteria","55":"/architecture/generated-documentation#implementation-references","56":"/architecture/#architecture","57":"/architecture/identity#identity","58":"/architecture/identity#purpose","59":"/architecture/identity#ownership","60":"/architecture/identity#canonical-identity","61":"/architecture/identity#persistence","62":"/architecture/identity#lifecycle","63":"/architecture/identity#system-identity","64":"/architecture/identity#target-placement-and-contracts","65":"/architecture/identity#migration-constraints","66":"/architecture/identity#lifecycle-1","67":"/architecture/identity#explicit-non-responsibilities","68":"/architecture/identity#per-identity-configuration","69":"/architecture/identity#audit","70":"/architecture/identity#current-implementation","71":"/architecture/identity#current-enforcement-and-isolation","72":"/architecture/identity#current-hazards","73":"/architecture/messaging-and-work-intake#messaging-and-work-intake","74":"/architecture/messaging-and-work-intake#purpose","75":"/architecture/messaging-and-work-intake#confirmed-boundary","76":"/architecture/messaging-and-work-intake#conversation-identity","77":"/architecture/messaging-and-work-intake#canonical-messages","78":"/architecture/messaging-andLine truncated
@@ -1,9 +0,0 @@
var Ot=Object.defineProperty;var At=(a,e,t)=>e in a?Ot(a,e,{enumerable:!0,configurable:!0,writable:!0,value:t}):a[e]=t;var Me=(a,e,t)=>At(a,typeof e!="symbol"?e+"":e,t);import{V as Ct,q as Be,ah as Mt,h as be,ai as nt,aj as Lt,ak as Dt,al as Pt,G as ce,d as zt,am as rt,p as he,an as Vt,ao as jt,s as $t,ap as Bt,v as Le,P as ve,O as xe,aq as Wt,ar as Kt,W as Jt,R as qt,$ as Ut,o as q,b as Ht,j as T,a0 as Gt,k as P,as as Qt,at as Yt,au as Zt,c as Q,n as it,e as _e,B as st,F as at,a as pe,t as me,av as Xt,aw as ot,ax as en,a6 as tn,ab as nn,ay as rn,_ as sn}from"./framework.BWuWLRhz.js";import{u as an,c as on}from"./theme.B97NJxv0.js";const ln={root:()=>Ct(()=>import("./@localSearchIndexroot.U0pDy-dK.js"),[])};/*!
* tabbable 6.5.0
* @license MIT, https://github.com/focus-trap/tabbable/blob/master/LICENSE
*/var gt=["input:not([inert]):not([inert] *)","select:not([inert]):not([inert] *)","textarea:not([inert]):not([inert] *)","a[href]:not([inert]):not([inert] *)","area[href]:not([inert]):not([inert] *)","button:not([inert]):not([inert] *)","[tabindex]:not(slot):not([inert]):not([inert] *)","audio[controls]:not([inert]):not([inert] *)","video[controls]:not([inert]):not([inert] *)",'[contenteditable]:not([contenteditable="false"]):not([inert]):not([inert] *)',"details>summary:first-of-type:not([inert]):not([inert] *)","details:not([inert]):not([inert] *)"],ke=gt.join(","),bt=typeof Element>"u",ae=bt?function(){}:Element.prototype.matches||Element.prototype.msMatchesSelector||Element.prototype.webkitMatchesSelector,Ne=!bt&&Element.prototype.getRootNode?function(a){var e;return a==null||(e=a.getRootNode)===null||e===void 0?void 0:e.call(a)}:function(a){return a==null?void 0:a.ownerDocument},Fe=function(e,t){var n;t===void 0&&(t=!0);var r=e==null||(n=e.getAttribute)===null||n===void 0?void 0:n.call(e,"inert"),s=r===""||r==="true",i=s||t&&e&&(typeof e.closest=="function"?e.closest("[inert]"):Fe(e.parentNode));return i},cn=function(e){var t,n=e==null||(t=e.getAttribute)===null||t===void 0?void 0:t.call(e,"contenteditable");return n===""||n==="true"},yt=function(e,t,n){if(Fe(e))return[];var r=Array.prototype.slice.apply(e.querySelectorAll(ke));return t&&ae.call(e,ke)&&r.unshift(e),r=r.filter(n),r},Re=function(e,t,n){for(var r=[],s=Array.from(e);s.length;){var i=s.shift();if(!Fe(i,!1))if(i.tagName==="SLOT"){var o=i.assignedElements(),l=o.length?o:i.children,c=Re(l,!0,n);n.flatten?r.push.apply(r,c):r.push({scopeParent:i,candidates:c})}else{var h=ae.call(i,ke);h&&n.filter(i)&&(t||!e.includes(i))&&r.push(i);var m=i.shadowRoot||typeof n.getShadowRoot=="function"&&n.getShadowRoot(i),p=!Fe(m,!1)&&(!n.shadowRootFilter||n.shadowRootFilter(i));if(m&&p){var b=Re(m===!0?i.children:m.children,!0,n);n.flatten?r.push.apply(r,b):r.push({scopeParent:i,candidates:b})}else s.unshift.apply(s,i.children)}}return r},wt=function(e){return!isNaN(parseInt(e.getAttribute("tabindex"),10))},se=function(e){if(!e)throw new Error("No node provided");return e.tabIndex<0&&(/^(AUDIO|VIDEO|DETAILS)$/.test(e.tagName)||cn(e))&&!wt(e)?0:e.tabIndex},un=function(e,t){var n=se(e);return n<0&&t&&!wt(e)?0:n},dn=function(e,t){return e.tabIndex===t.tabIndex?e.documentOrder-t.documentOrder:e.tabIndex-t.tabIndex},St=function(e){return e.tagName==="INPUT"},fn=function(e){return St(e)&&e.type==="hidden"},hn=function(e){var t=e.tagName==="DETAILS"&&Array.prototype.slice.apply(e.children).some(function(n){return n.tagName==="SUMMARY"});return t},vn=function(e,t){for(var n=0;n<e.length;n++)if(e[n].checked&&e[n].form===t)return e[n]},pn=function(e){if(!e.name)return!0;var t=e.form||Ne(e),n=function(o){return t.querySelectorAll('input[type="radio"][name="'+o+'"]')},r;if(typeof window<"u"&&typeof window.CSS<"u"&&typeof window.CSS.escape=="function")r=n(window.CSS.escape(e.name));else try{r=n(e.name)}catch(i){return console.error("Looks like you have a radio button with a name attribute containing invalid CSS selector characters and need the CSS.escape polyfill: %s",i.message),!1}var s=vn(r,e.form);return!s||s===e},mn=function(e){return St(e)&&e.type==="radio"},gn=function(e){return mn(e)&&!pn(e)},bn=function(e){var t,n=e&&Ne(e),r=(t=n)===null||t===void 0?void 0:t.host,s=!1;if(n&&n!==e){var i,o,l;for(s=!!((i=r)!==null&&i!==void 0&&(o=i.ownerDocument)!==null&&o!==void 0&&o.contains(r)||e!=null&&(l=e.ownerDocument)!==null&&l!==void 0&&l.contains(e));!s&&r;){var c,h,m;n=Ne(r),r=(c=n)===null||c===void 0?void 0:c.host,s=!!((h=r)!==null&&h!==void 0&&(m=h.ownerDocument)!==null&&m!==void 0&&m.contains(r))}}return s},lt=function(e){var t=e.getBoundingClientRect(),n=t.width,r=t.height;return n===0&&r===0},yn=function(e,t){var n=t.displayCheck,r=t.getShadowRoot;if(n==="full-native"&&"checkVisibility"in e){var s=e.checkVisibility({checkOpacity:!1,opacityProperty:!1,contentVisibilityAuto:!0,visibilityProperty:!0,checkVisibilityCSS:!0});return!s}var i=getComputedStyle(e),o=i.visibility;if(o==="hidden"||o==="collapse")return!0;var l=ae.call(e,"details>summary:first-of-type"),c=l?e.parentElement:e;if(ae.call(c,"details:not([open]) *"))return!0;if(!n||n==="full"||n==="full-native"||n==="legacy-full"){if(typeof r=="function"){for(var h=e;e;){var m=e.parentElement,p=Ne(e);if(m&&!m.shadowRoot&&r(m)===!0)return lt(e);e.assignedSlot?e=e.assignedSlot:!m&&p!==e.ownerDocument?e=p.host:e=m}e=h}if(bn(e))return!e.getClientRects().length;if(n!=="legacy-full")return!0}else if(n==="non-zero-area")return lt(e);return!1},wn=function(e){if(/^(INPUT|BUTTON|SELECT|TEXTAREA)$/.test(e.tagName))for(var t=e.parentElement;t;){if(t.tagName==="FIELDSET"&&t.disabled){for(var n=0;n<t.children.length;n++){var r=t.children.item(n);if(r.tagName==="LEGEND")return ae.call(t,"fieldset[disabled] *")?!0:!r.contains(e)}return!0}t=t.parentElement}return!1},Oe=function(e,t){return!(t.disabled||fn(t)||yn(t,e)||hn(t)||wn(t))},WLine truncated
* focus-trap 7.8.0
* @license MIT, https://github.com/focus-trap/focus-trap/blob/master/LICENSE
*/function Ke(a,e){(e==null||e>a.length)&&(e=a.length);for(var t=0,n=Array(e);t<e;t++)n[t]=a[t];return n}function En(a){if(Array.isArray(a))return Ke(a)}function ct(a,e){var t=typeof Symbol<"u"&&a[Symbol.iterator]||a["@@iterator"];if(!t){if(Array.isArray(a)||(t=_t(a))||e){t&&(a=t);var n=0,r=function(){};return{s:r,n:function(){return n>=a.length?{done:!0}:{done:!1,value:a[n++]}},e:function(l){throw l},f:r}}throw new TypeError(`Invalid attempt to iterate non-iterable instance.
In order to be iterable, non-array objects must have a [Symbol.iterator]() method.`)}var s,i=!0,o=!1;return{s:function(){t=t.call(a)},n:function(){var l=t.next();return i=l.done,l},e:function(l){o=!0,s=l},f:function(){try{i||t.return==null||t.return()}finally{if(o)throw s}}}}function In(a,e,t){return(e=On(e))in a?Object.defineProperty(a,e,{value:t,enumerable:!0,configurable:!0,writable:!0}):a[e]=t,a}function kn(a){if(typeof Symbol<"u"&&a[Symbol.iterator]!=null||a["@@iterator"]!=null)return Array.from(a)}function Nn(){throw new TypeError(`Invalid attempt to spread non-iterable instance.
In order to be iterable, non-array objects must have a [Symbol.iterator]() method.`)}function ut(a,e){var t=Object.keys(a);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(a);e&&(n=n.filter(function(r){return Object.getOwnPropertyDescriptor(a,r).enumerable})),t.push.apply(t,n)}return t}function dt(a){for(var e=1;e<arguments.length;e++){var t=arguments[e]!=null?arguments[e]:{};e%2?ut(Object(t),!0).forEach(function(n){In(a,n,t[n])}):Object.getOwnPropertyDescriptors?Object.defineProperties(a,Object.getOwnPropertyDescriptors(t)):ut(Object(t)).forEach(function(n){Object.defineProperty(a,n,Object.getOwnPropertyDescriptor(t,n))})}return a}function Fn(a){return En(a)||kn(a)||_t(a)||Nn()}function Rn(a,e){if(typeof a!="object"||!a)return a;var t=a[Symbol.toPrimitive];if(t!==void 0){var n=t.call(a,e);if(typeof n!="object")return n;throw new TypeError("@@toPrimitive must return a primitive value.")}return(e==="string"?String:Number)(a)}function On(a){var e=Rn(a,"string");return typeof e=="symbol"?e:e+""}function _t(a,e){if(a){if(typeof a=="string")return Ke(a,e);var t={}.toString.call(a).slice(8,-1);return t==="Object"&&a.constructor&&(t=a.constructor.name),t==="Map"||t==="Set"?Array.from(a):t==="Arguments"||/^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t)?Ke(a,e):void 0}}var U={getActiveTrap:function(e){return(e==null?void 0:e.length)>0?e[e.length-1]:null},activateTrap:function(e,t){var n=U.getActiveTrap(e);t!==n&&U.pauseTrap(e);var r=e.indexOf(t);r===-1||e.splice(r,1),e.push(t)},deactivateTrap:function(e,t){var n=e.indexOf(t);n!==-1&&e.splice(n,1),U.unpauseTrap(e)},pauseTrap:function(e){var t=U.getActiveTrap(e);t==null||t._setPausedState(!0)},unpauseTrap:function(e){var t=U.getActiveTrap(e);t&&!t._isManuallyPaused()&&t._setPausedState(!1)}},An=function(e){return e.tagName&&e.tagName.toLowerCase()==="input"&&typeof e.select=="function"},Cn=function(e){return(e==null?void 0:e.key)==="Escape"||(e==null?void 0:e.key)==="Esc"||(e==null?void 0:e.keyCode)===27},ye=function(e){return(e==null?void 0:e.key)==="Tab"||(e==null?void 0:e.keyCode)===9},Mn=function(e){return ye(e)&&!e.shiftKey},Ln=function(e){return ye(e)&&e.shiftKey},ft=function(e){return setTimeout(e,0)},ge=function(e){for(var t=arguments.length,n=new Array(t>1?t-1:0),r=1;r<t;r++)n[r-1]=arguments[r];return typeof e=="function"?e.apply(void 0,n):e},Te=function(e){return e.target.shadowRoot&&typeof e.composedPath=="function"?e.composedPath()[0]:e.target},Dn=[],Pn=function(e,t){var n=(t==null?void 0:t.document)||document,r=(t==null?void 0:t.trapStack)||Dn,s=dt({returnFocusOnDeactivate:!0,escapeDeactivates:!0,delayInitialFocus:!0,isolateSubtrees:!1,isKeyForward:Mn,isKeyBackward:Ln},t),i={containers:[],containerGroups:[],tabbableGroups:[],adjacentElements:new Set,alreadySilent:new Set,nodeFocusedBeforeActivation:null,mostRecentlyFocusedNode:null,active:!1,paused:!1,manuallyPaused:!1,delayInitialFocusTimer:void 0,recentNavEvent:void 0},o,l=function(u,f,g){return u&&u[f]!==void 0?u[f]:s[g||f]},c=function(u,f){var g=typeof(f==null?void 0:f.composedPath)=="function"?f.composedPath():void 0;return i.containerGroups.findIndex(function(E){var _=E.container,I=E.tabbableNodes;return _.contains(u)||(g==null?void 0:g.includes(_))||I.find(function(S){return S===u})})},h=function(u){var f=arguments.length>1&&arguments[1]!==void 0?arguments[1]:{},g=f.hasFallback,E=g===void 0?!1:g,_=f.params,I=_===void 0?[]:_,S=s[u];if(typeof S=="function"&&(S=S.apply(void 0,Fn(I))),S===!0&&(S=void 0),!S){if(S===void 0||S===!1)return S;throw new Error("`".concat(u,"` was specified but was not a node, or did not return a node"))}var v=S;if(typeof S=="string"){try{v=n.querySelector(S)}catch(d){throw new Error("`".concat(u,'` appears to be an invalid selector; error="').concat(d.message,'"'))}if(!v&&!E)throw new Error("`".concat(u,"` as selector refers to no known node"))}return v},m=function(){var u=h("initialFocus",{hasFallback:!0});if(u===!1)return!1;if(u===void 0||u&&!De(u,s.tabbableOptions))if(c(n.activeElement)>=0)u=n.activeElement;else{var f=i.tabbableGroups[0],g=f&&f.firstTabbableNode;u=g||h("fallbackFocus")}else u===null&&(u=h("fallbackFocus"));if(!u)throw new Error("Your focus-trap needs to have at least one focusable element");return u},p=function(){if(i.containerGroups=i.containers.map(function(u){var f=xn(u,s.tabbableOptions),g=_n(u,s.tabbableOptions),E=f.length>0?f[0]:void 0,_=f.length>0?f[f.length-1]:void 0,I=g.find(function(d){return oe(d)}),S=g.slice().reverse().find(function(d){return oe(d)}),v=!!f.find(function(d){return se(d)>0});return{container:u,tabbableNodes:f,focusableNodes:g,posTabIndexesFound:v,firstTabbableNode:E,lastTabbableNode:_,firstDomTabbableNode:I,lastDomTabbableNode:S,nextTabbableNode:function(x){var R=arguments.length>1&&arguments[1]!==void 0?arguments[1]:!0,A=f.indexOf(x);return A<0?R?g.slice(g.indexOf(x)+1).find(function(C){return oe(C)}):g.slice(0,g.indexOf(x)).reverse().find(function(C){return oe(C)}):f[A+(R?1:-1)]}}}),i.tabbableGroups=i.conLine truncated
@@ -1,19 +0,0 @@
/**
* @vue/shared v3.5.39
* (c) 2018-present Yuxi (Evan) You and Vue contributors
* @license MIT
**/function Xs(e){const t=Object.create(null);for(const n of e.split(","))t[n]=1;return n=>n in t}const se={},Ft=[],Je=()=>{},_i=()=>!1,dn=e=>e.charCodeAt(0)===111&&e.charCodeAt(1)===110&&(e.charCodeAt(2)>122||e.charCodeAt(2)<97),Gn=e=>e.startsWith("onUpdate:"),ge=Object.assign,Ys=(e,t)=>{const n=e.indexOf(t);n>-1&&e.splice(n,1)},ll=Object.prototype.hasOwnProperty,Z=(e,t)=>ll.call(e,t),B=Array.isArray,Dt=e=>hn(e)==="[object Map]",bi=e=>hn(e)==="[object Set]",Sr=e=>hn(e)==="[object Date]",K=e=>typeof e=="function",ce=e=>typeof e=="string",Le=e=>typeof e=="symbol",Q=e=>e!==null&&typeof e=="object",wi=e=>(Q(e)||K(e))&&K(e.then)&&K(e.catch),Si=Object.prototype.toString,hn=e=>Si.call(e),cl=e=>hn(e).slice(8,-1),Ti=e=>hn(e)==="[object Object]",Xn=e=>ce(e)&&e!=="NaN"&&e[0]!=="-"&&""+parseInt(e,10)===e,wt=Xs(",key,ref,ref_for,ref_key,onVnodeBeforeMount,onVnodeMounted,onVnodeBeforeUpdate,onVnodeUpdated,onVnodeBeforeUnmount,onVnodeUnmounted"),Yn=e=>{const t=Object.create(null);return n=>t[n]||(t[n]=e(n))},al=/-\w/g,Ce=Yn(e=>e.replace(al,t=>t.slice(1).toUpperCase())),ul=/\B([A-Z])/g,pt=Yn(e=>e.replace(ul,"-$1").toLowerCase()),Jn=Yn(e=>e.charAt(0).toUpperCase()+e.slice(1)),On=Yn(e=>e?`on${Jn(e)}`:""),Ye=(e,t)=>!Object.is(e,t),Pn=(e,...t)=>{for(let n=0;n<e.length;n++)e[n](...t)},Ei=(e,t,n,s=!1)=>{Object.defineProperty(e,t,{configurable:!0,enumerable:!1,writable:s,value:n})},Js=e=>{const t=parseFloat(e);return isNaN(t)?e:t},fl=e=>{const t=ce(e)?Number(e):NaN;return isNaN(t)?e:t};let Tr;const zn=()=>Tr||(Tr=typeof globalThis<"u"?globalThis:typeof self<"u"?self:typeof window<"u"?window:typeof global<"u"?global:{});function zs(e){if(B(e)){const t={};for(let n=0;n<e.length;n++){const s=e[n],r=ce(s)?gl(s):zs(s);if(r)for(const i in r)t[i]=r[i]}return t}else if(ce(e)||Q(e))return e}const dl=/;(?![^(]*\))/g,hl=/:([^]+)/,pl=/\/\*[^]*?\*\//g;function gl(e){const t={};return e.replace(pl,"").split(dl).forEach(n=>{if(n){const s=n.split(hl);s.length>1&&(t[s[0].trim()]=s[1].trim())}}),t}function Qs(e){let t="";if(ce(e))t=e;else if(B(e))for(let n=0;n<e.length;n++){const s=Qs(e[n]);s&&(t+=s+" ")}else if(Q(e))for(const n in e)e[n]&&(t+=n+" ");return t.trim()}const ml="itemscope,allowfullscreen,formnovalidate,ismap,nomodule,novalidate,readonly",yl=Xs(ml);function xi(e){return!!e||e===""}function vl(e,t){if(e.length!==t.length)return!1;let n=!0;for(let s=0;n&&s<e.length;s++)n=Zs(e[s],t[s]);return n}function Zs(e,t){if(e===t)return!0;let n=Sr(e),s=Sr(t);if(n||s)return n&&s?e.getTime()===t.getTime():!1;if(n=Le(e),s=Le(t),n||s)return e===t;if(n=B(e),s=B(t),n||s)return n&&s?vl(e,t):!1;if(n=Q(e),s=Q(t),n||s){if(!n||!s)return!1;const r=Object.keys(e).length,i=Object.keys(t).length;if(r!==i)return!1;for(const o in e){const l=e.hasOwnProperty(o),c=t.hasOwnProperty(o);if(l&&!c||!l&&c||!Zs(e[o],t[o]))return!1}}return String(e)===String(t)}const Ci=e=>!!(e&&e.__v_isRef===!0),_l=e=>ce(e)?e:e==null?"":B(e)||Q(e)&&(e.toString===Si||!K(e.toString))?Ci(e)?_l(e.value):JSON.stringify(e,Ai,2):String(e),Ai=(e,t)=>Ci(t)?Ai(e,t.value):Dt(t)?{[`Map(${t.size})`]:[...t.entries()].reduce((n,[s,r],i)=>(n[fs(s,i)+" =>"]=r,n),{})}:bi(t)?{[`Set(${t.size})`]:[...t.values()].map(n=>fs(n))}:Le(t)?fs(t):Q(t)&&!B(t)&&!Ti(t)?String(t):t,fs=(e,t="")=>{var n;return Le(e)?`Symbol(${(n=e.description)!=null?n:t})`:e};/**
* @vue/reactivity v3.5.39
* (c) 2018-present Yuxi (Evan) You and Vue contributors
* @license MIT
**/let pe;class bl{constructor(t=!1){this.detached=t,this._active=!0,this._on=0,this.effects=[],this.cleanups=[],this._isPaused=!1,this._warnOnRun=!0,this.__v_skip=!0,!t&&pe&&(pe.active?(this.parent=pe,this.index=(pe.scopes||(pe.scopes=[])).push(this)-1):(this._active=!1,this._warnOnRun=!1))}get active(){return this._active}pause(){if(this._active){this._isPaused=!0;let t,n;if(this.scopes)for(t=0,n=this.scopes.length;t<n;t++)this.scopes[t].pause();for(t=0,n=this.effects.length;t<n;t++)this.effects[t].pause()}}resume(){if(this._active&&this._isPaused){this._isPaused=!1;let t,n;if(this.scopes)for(t=0,n=this.scopes.length;t<n;t++)this.scopes[t].resume();for(t=0,n=this.effects.length;t<n;t++)this.effects[t].resume()}}run(t){if(this._active){const n=pe;try{return pe=this,t()}finally{pe=n}}}on(){++this._on===1&&(this.prevScope=pe,pe=this)}off(){if(this._on>0&&--this._on===0){if(pe===this)pe=this.prevScope;else{let t=pe;for(;t;){if(t.prevScope===this){t.prevScope=this.prevScope;break}t=t.prevScope}}this.prevScope=void 0}}stop(t){if(this._active){this._active=!1;let n,s;for(n=0,s=this.effects.length;n<s;n++)this.effects[n].stop();for(this.effects.length=0,n=0,s=this.cleanups.length;n<s;n++)this.cleanups[n]();if(this.cleanups.length=0,this.scopes){for(n=0,s=this.scopes.length;n<s;n++)this.scopes[n].stop(!0);this.scopes.length=0}if(!this.detached&&this.parent&&!t){const r=this.parent.scopes.pop();r&&r!==this&&(this.parent.scopes[this.index]=r,r.index=this.index)}this.parent=void 0}}}function Ri(){return pe}function wl(e,t=!1){pe&&pe.cleanups.push(e)}let ie;const ds=new WeakSet;class Mi{constructor(t){this.fn=t,this.deps=void 0,this.depsTail=void 0,this.flags=5,this.next=void 0,this.cleanup=void 0,this.scheduler=void 0,pe&&(pe.active?pe.effects.push(this):this.flags&=-2)}pause(){this.flags|=64}resume(){this.flags&64&&(this.flags&=-65,ds.has(this)&&(ds.delete(this),this.trigger()))}notify(){this.flags&2&&!(this.flags&32)||this.flags&8||Pi(this)}run(){if(!(this.flags&1))return this.fn();this.flags|=2,Er(this),Li(this);const t=ie,n=Ve;ie=this,Ve=!0;try{return this.fn()}finally{Ii(this),ie=t,Ve=n,this.flags&=-3}}stop(){if(this.flags&1){for(let t=this.deps;t;t=t.nextDep)nr(t);this.deps=this.depsTail=void 0,Er(this),this.onStop&&this.onStop(),this.flags&=-2}}trigger(){this.flags&64?ds.add(this):this.scheduler?this.scheduler():this.runIfDirty()}runIfDirty(){Is(this)&&this.run()}get dirty(){return Is(this)}}let Oi=0,zt,Qt;function Pi(e,t=!1){if(e.flags|=8,t){e.next=Qt,Qt=e;return}e.next=zt,zt=e}function er(){Oi++}function tr(){if(--Oi>0)return;if(Qt){let t=Qt;for(Qt=void 0;t;){const n=t.next;t.next=void 0,t.flags&=-9,t=n}}let e;for(;zt;){let t=zt;for(zt=void 0;t;){const n=t.next;if(t.next=void 0,t.flags&=-9,t.flags&1)try{t.trigger()}catch(s){e||(e=s)}t=n}}if(e)throw e}function Li(e){for(let t=e.deps;t;t=t.nextDep)t.version=-1,t.prevActiveLink=t.dep.activeLink,t.dep.activeLink=t}function Ii(e){let t,n=e.depsTail,s=n;for(;s;){const r=s.prevDep;s.version===-1?(s===n&&(n=r),nr(s),Sl(s)):t=s,s.dep.activeLink=s.prevActiveLink,s.prevActiveLink=void 0,s=r}e.deps=t,e.depsTail=n}function Is(e){for(let t=e.deps;t;t=t.nextDep)if(t.dep.version!==t.version||t.dep.computed&&(Ni(t.dep.computed)||t.dep.version!==t.version))return!0;return!!e._dirty}function Ni(e){if(e.flags&4&&!(e.flags&16)||(e.flags&=-17,e.globalVersion===sn)||(e.globalVersion=sn,!e.isSSR&&e.flags&128&&(!e.deps&&!e._dirty||!Is(e))))return;e.flags|=2;const t=e.dep,n=ie,s=Ve;ie=e,Ve=!0;try{Li(e);const r=e.fn(e._value);(t.version===0||Ye(r,e._value))&&(e.flags|=128,e._value=r,t.version++)}catch(r){throw t.version++,r}finally{ie=n,Ve=s,Ii(e),e.flags&=-3}}function nr(e,t=!1){const{dep:n,prevSub:s,nextSub:r}=e;if(s&&(s.nextSub=r,e.prevSub=void 0),r&&(r.prevSub=s,e.nextSub=void 0),n.subs===e&&(n.subs=s,!s&&n.computed)){n.computed.flags&=-5;for(let i=n.computed.deps;i;i=i.nextDep)nr(i,!0)}!t&&!--n.sc&&n.map&&n.map.delete(n.key)}function Sl(e){const{prevDep:t,nextDep:n}=e;t&&(t.nextDep=n,e.prevDep=void 0),n&&(n.prevDep=t,e.nextDep=void 0)}let Ve=!0;const Fi=[];function ze(){Fi.push(Ve),Ve=!1}function Qe(){const e=Fi.pop();Ve=e===void 0?!0:e}function Er(e){const{cleanup:t}=e;if(e.cleanup=void 0,t){const n=ie;ie=void 0;try{t()}finally{ie=n}}}let sn=0;class Tl{constructor(t,n){this.sub=t,this.dep=n,this.version=n.version,this.nextDep=this.prevDep=this.nextSub=this.prevSub=this.prevActiveLink=void 0}}class Qn{constructor(t){this.computed=t,this.version=0,this.activeLink=void 0,this.subs=void 0,this.map=void 0,this.key=void 0,this.sc=0,this.__v_skip=!0}track(t){if(!ie||!Ve||ie===this.computed)return;let n=this.activeLink;if(n===void 0||n.sub!==ie)n=this.activeLink=new Tl(ie,this),ie.deps?(n.prevDep=ie.depsTail,ie.depsTail.nextDep=n,ie.depsTail=n):ie.deps=ie.depsTail=n,Di(n);else if(n.version===-1&&(n.version=this.version,n.nextDep)){const s=n.nextDep;s.prevDep=n.prevDep,n.prevDep&&(n.prevDep.nextDep=s),n.prevDep=ie.depsTail,n.nextDep=void 0,ie.depsTail.nextDep=n,ie.depsTail=n,ie.deps===nLine truncated
* @vue/runtime-core v3.5.39
* (c) 2018-present Yuxi (Evan) You and Vue contributors
* @license MIT
**/function pn(e,t,n,s){try{return s?e(...s):e()}catch(r){gn(r,t,n)}}function $e(e,t,n,s){if(K(e)){const r=pn(e,t,n,s);return r&&wi(r)&&r.catch(i=>{gn(i,t,n)}),r}if(B(e)){const r=[];for(let i=0;i<e.length;i++)r.push($e(e[i],t,n,s));return r}}function gn(e,t,n,s=!0){const r=t?t.vnode:null,{errorHandler:i,throwUnhandledErrorInProduction:o}=t&&t.appContext.config||se;if(t){let l=t.parent;const c=t.proxy,u=`https://vuejs.org/error-reference/#runtime-${n}`;for(;l;){const a=l.ec;if(a){for(let d=0;d<a.length;d++)if(a[d](e,c,u)===!1)return}l=l.parent}if(i){ze(),pn(i,null,10,[e,c,u]),Qe();return}}Zl(e,n,r,s,o)}function Zl(e,t,n,s=!0,r=!1){if(r)throw e;console.error(e)}const Ee=[];let qe=-1;const Ht=[];let ut=null,Lt=0;const Ki=Promise.resolve();let $n=null;function ns(e){const t=$n||Ki;return e?t.then(this?e.bind(this):e):t}function ec(e){let t=qe+1,n=Ee.length;for(;t<n;){const s=t+n>>>1,r=Ee[s],i=ln(r);i<e||i===e&&r.flags&2?t=s+1:n=s}return t}function ir(e){if(!(e.flags&1)){const t=ln(e),n=Ee[Ee.length-1];!n||!(e.flags&2)&&t>=ln(n)?Ee.push(e):Ee.splice(ec(t),0,e),e.flags|=1,qi()}}function qi(){$n||($n=Ki.then(Gi))}function tc(e){B(e)?Ht.push(...e):ut&&e.id===-1?ut.splice(Lt+1,0,e):e.flags&1||(Ht.push(e),e.flags|=1),qi()}function Cr(e,t,n=qe+1){for(;n<Ee.length;n++){const s=Ee[n];if(s&&s.flags&2){if(e&&s.id!==e.uid)continue;Ee.splice(n,1),n--,s.flags&4&&(s.flags&=-2),s(),s.flags&4||(s.flags&=-2)}}}function jn(e){if(Ht.length){const t=[...new Set(Ht)].sort((n,s)=>ln(n)-ln(s));if(Ht.length=0,ut){ut.push(...t);return}for(ut=t,Lt=0;Lt<ut.length;Lt++){const n=ut[Lt];n.flags&4&&(n.flags&=-2),n.flags&8||n(),n.flags&=-2}ut=null,Lt=0}}const ln=e=>e.id==null?e.flags&2?-1:1/0:e.id;function Gi(e){try{for(qe=0;qe<Ee.length;qe++){const t=Ee[qe];t&&!(t.flags&8)&&(t.flags&4&&(t.flags&=-2),pn(t,t.i,t.i?15:14),t.flags&4||(t.flags&=-2))}}finally{for(;qe<Ee.length;qe++){const t=Ee[qe];t&&(t.flags&=-2)}qe=-1,Ee.length=0,jn(),$n=null,(Ee.length||Ht.length)&&Gi()}}let ve=null,Xi=null;function Vn(e){const t=ve;return ve=e,Xi=e&&e.type.__scopeId||null,t}function nc(e,t=ve,n){if(!t||e._n)return e;const s=(...r)=>{s._d&&Bn(-1);const i=Vn(t);let o;try{o=e(...r)}finally{Vn(i),s._d&&Bn(1)}return o};return s._n=!0,s._c=!0,s._d=!0,s}function Yu(e,t){if(ve===null)return e;const n=os(ve),s=e.dirs||(e.dirs=[]);for(let r=0;r<t.length;r++){let[i,o,l,c=se]=t[r];i&&(K(i)&&(i={mounted:i,updated:i}),i.deep&&rt(o),s.push({dir:i,instance:n,value:o,oldValue:void 0,arg:l,modifiers:c}))}return e}function Ge(e,t,n,s){const r=e.dirs,i=t&&t.dirs;for(let o=0;o<r.length;o++){const l=r[o];i&&(l.oldValue=i[o].value);let c=l.dir[s];c&&(ze(),$e(c,n,8,[e.el,l,e,t]),Qe())}}function sc(e,t){if(ye){let n=ye.provides;const s=ye.parent&&ye.parent.provides;s===n&&(n=ye.provides=Object.create(s)),n[e]=t}}function Tt(e,t,n=!1){const s=Rt();if(s||xt){let r=xt?xt._context.provides:s?s.parent==null||s.ce?s.vnode.appContext&&s.vnode.appContext.provides:s.parent.provides:void 0;if(r&&e in r)return r[e];if(arguments.length>1)return n&&K(t)?t.call(s&&s.proxy):t}}function Yi(){return!!(Rt()||xt)}const rc=Symbol.for("v-scx"),ic=()=>Tt(rc);function or(e,t){return ss(e,null,t)}function Ju(e,t){return ss(e,null,{flush:"post"})}function He(e,t,n){return ss(e,t,n)}function ss(e,t,n=se){const{immediate:s,deep:r,flush:i,once:o}=n,l=ge({},n),c=t&&s||!t&&i!=="post";let u;if(kt){if(i==="sync"){const _=ic();u=_.__watcherHandles||(_.__watcherHandles=[])}else if(!c){const _=()=>{};return _.stop=Je,_.resume=Je,_.pause=Je,_}}const a=ye;l.call=(_,b,y)=>$e(_,a,b,y);let d=!1;i==="post"?l.scheduler=_=>{Te(_,a&&a.suspense)}:i!=="sync"&&(d=!0,l.scheduler=(_,b)=>{b?_():ir(_)}),l.augmentJob=_=>{t&&(_.flags|=4),d&&(_.flags|=2,a&&(_.id=a.uid,_.i=a))};const m=Ql(e,t,l);return kt&&(u?u.push(m):c&&m()),m}function oc(e,t,n){const s=this.proxy,r=ce(e)?e.includes(".")?Ji(s,e):()=>s[e]:e.bind(s,s);let i;K(t)?i=t:(i=t.handler,n=t);const o=vn(this),l=ss(r,i.bind(s),n);return o(),l}function Ji(e,t){const n=t.split(".");return()=>{let s=e;for(let r=0;r<n.length&&s;r++)s=s[n[r]];return s}}const at=new WeakMap,zi=Symbol("_vte"),Qi=e=>e.__isTeleport,_t=e=>e&&(e.disabled||e.disabled===""),lc=e=>e&&(e.defer||e.defer===""),Ar=e=>typeof SVGElement<"u"&&e instanceof SVGElement,Rr=e=>typeof MathMLElement=="function"&&e instanceof MathMLElement,Ds=(e,t)=>{const n=e&&e.to;return ce(n)?t?t(n):null:n},cc={name:"Teleport",__isTeleport:!0,process(e,t,n,s,r,i,o,l,c,u){const{mc:a,pc:d,pbc:m,o:{insert:_,querySelector:b,createText:y,createComment:F,parentNode:O}}=u,P=_t(t.props);let{dynamicChildren:p}=t;const g=(S,j,T)=>{S.shapeFlag&16&&a(S.children,j,T,r,i,o,l,c)},R=(S=t)=>{const j=_t(S.props),T=S.target=Ds(S.props,b),H=Hs(T,S,y,_);T&&(o!=="svg"&&Ar(T)?o="svg":o!=="mathml"&&Rr(T)&&(o="mathml"),r&&r.isCE&&(r.ce._teleportTargets||(r.ce._teleportTargets=new Set)).add(T),j||(g(S,T,H),Xt(S,!1)))},V=S=>{const j=()=>{if(at.get(S)===j){if(at.delete(S),_t(S.props)){const T=O(S.el)||n;g(S,T,S.anchor),Xt(S,!0)}R(S)}};at.set(S,j),Te(j,i)};if(e==null){ Line truncated
`&&(p.tagName==="PRE"||p.tagName==="TEXTAREA")&&(re=re.slice(1));const{textContent:oe}=p;oe!==re&&oe!==re.replace(/\r\n|\r/g,`
`)&&(In(p,0)||Pt(),p.textContent=g.children)}if(A){if(W||Y||!j||w&48){const re=p.tagName.includes("-");for(const oe in A)(W&&(oe.endsWith("value")||oe==="indeterminate")||dn(oe)&&!wt(oe)||oe[0]==="."||re&&!wt(oe)||H&&H.includes(oe))&&s(p,oe,null,A[oe],void 0,R)}else if(A.onClick)s(p,"onClick",null,A.onClick,void 0,R);else if(w&4&&ft(A.style))for(const re in A.style)A.style[re]}let _e;(_e=A&&A.onVnodeBeforeMount)&&Ne(_e,R,g),G&&Ge(g,null,R,"beforeMount"),((_e=A&&A.onVnodeMounted)||G||X)&&Oo(()=>{_e&&Ne(_e,R,g),X&&te.enter(p),G&&Ge(g,null,R,"mounted")},V)}return p.nextSibling},_=(p,g,R,V,S,j,T)=>{T=T||!!g.dynamicChildren;const H=g.children,A=H.length;let w=!1;for(let D=0;D<A;D++){const G=T?H[D]:H[D]=De(H[D]),te=G.type===Ct;p?(te&&!T&&D+1<A&&De(H[D+1]).type===Ct&&(c(r(p.data.slice(G.children.length)),R,i(p)),p.data=G.children),p=d(p,G,V,S,j,T)):te&&!G.children?c(G.el=r(""),R):(w||(w=!0,In(R,1)||Pt()),n(null,G,R,null,V,S,En(R),j))}return p},b=(p,g,R,V,S,j)=>{const{slotScopeIds:T}=g;T&&(S=S?S.concat(T):T);const H=o(p),A=_(i(p),g,H,R,V,S,j);return A&&Nt(A)&&A.data==="]"?i(g.anchor=A):(Pt(),c(g.anchor=u("]"),H,A),A)},y=(p,g,R,V,S,j)=>{if(yc(p,g)||Pt(),g.el=null,j){const A=F(p);for(;;){const w=i(p);if(w&&w!==A)l(w);else break}}const T=i(p),H=o(p);return l(p),n(null,g,H,T,R,V,En(H),S),R&&(R.vnode.el=g.el,mo(R,g.el)),T},F=(p,g="[",R="]")=>{let V=0;for(;p;)if(p=i(p),p&&Nt(p)&&(p.data===g&&V++,p.data===R)){if(V===0)return i(p);V--}return p},O=(p,g,R)=>{const V=g.parentNode;V&&V.replaceChild(p,g);let S=R;for(;S;)S.vnode.el===g&&(S.vnode.el=S.subTree.el=p),S=S.parent},P=p=>p.nodeType===1&&p.tagName==="TEMPLATE";return[a,d]}const Wn="data-allow-mismatch",mc={0:"text",1:"children",2:"class",3:"style",4:"attribute"};function In(e,t){if(t===0||t===1)for(;e&&!e.hasAttribute(Wn);)e=e.parentElement;return ar(e&&e.getAttribute(Wn),t)}function ar(e,t){if(e==null)return!1;if(e==="")return!0;{const n=e.split(",");return t===0&&n.includes("children")?!0:n.includes(mc[t])}}function yc(e,t){return In(e.parentElement,1)||vc(e)||_c(t)}function vc(e){return e.nodeType===1&&ar(e.getAttribute(Wn),1)}function _c({props:e}){const t=e&&e[Wn];return typeof t=="string"&&ar(t,1)}zn().requestIdleCallback;zn().cancelIdleCallback;function bc(e,t){if(Nt(e)&&e.data==="["){let n=1,s=e.nextSibling;for(;s;){if(s.nodeType===1){if(t(s)===!1)break}else if(Nt(s))if(s.data==="]"){if(--n===0)break}else s.data==="["&&n++;s=s.nextSibling}}else t(e)}const Et=e=>!!e.type.__asyncLoader;function Qu(e){K(e)&&(e={loader:e});const{loader:t,loadingComponent:n,errorComponent:s,delay:r=200,hydrate:i,timeout:o,suspensible:l=!0,onError:c}=e;let u=null,a,d=0;const m=()=>(d++,u=null,_()),_=()=>{let b;return u||(b=u=t().catch(y=>{if(y=y instanceof Error?y:new Error(String(y)),c)return new Promise((F,O)=>{c(y,()=>F(m()),()=>O(y),d+1)});throw y}).then(y=>b!==u&&u?u:(y&&(y.__esModule||y[Symbol.toStringTag]==="Module")&&(y=y.default),a=y,y)))};return lr({name:"AsyncComponentWrapper",__asyncLoader:_,__asyncHydrate(b,y,F){let O=!1;(y.bu||(y.bu=[])).push(()=>O=!0);const P=()=>{O||F()},p=i?()=>{const g=i(P,R=>bc(b,R));g&&(y.bum||(y.bum=[])).push(g)}:P;a?p():_().then(()=>!y.isUnmounted&&p())},get __asyncResolved(){return a},setup(){const b=ye;if(cr(b),a)return()=>xn(a,b);const y=R=>{u=null,gn(R,b,13,!s)};if(l&&b.suspense||kt)return _().then(R=>()=>xn(R,b)).catch(R=>(y(R),()=>s?de(s,{error:R}):null));const F=ke(!1),O=ke(),P=ke(!!r);let p,g;return yn(()=>{p!=null&&clearTimeout(p),g!=null&&clearTimeout(g)}),r&&(g=setTimeout(()=>{b.isUnmounted||(P.value=!1)},r)),o!=null&&(p=setTimeout(()=>{if(!b.isUnmounted&&!F.value&&!O.value){const R=new Error(`Async component timed out after ${o}ms.`);y(R),O.value=R}},o)),_().then(()=>{b.isUnmounted||(F.value=!0,b.parent&&mn(b.parent.vnode)&&b.parent.update())}).catch(R=>{if(b.isUnmounted){u=null;return}y(R),O.value=R}),()=>{if(F.value&&a)return xn(a,b);if(O.value&&s)return de(s,{error:O.value});if(n&&!P.value)return xn(n,b)}}})}function xn(e,t){const{ref:n,props:s,children:r,ce:i}=t.vnode,o=de(e,s,r);return o.ref=n,o.ce=i,delete t.vnode.ce,o}const mn=e=>e.type.__isKeepAlive;function wc(e,t){ro(e,"a",t)}function Sc(e,t){ro(e,"da",t)}function ro(e,t,n=ye){const s=e.__wdc||(e.__wdc=()=>{let r=n;for(;r;){if(r.isDeactivated)return;r=r.parent}return e()});if(rs(t,s,n),n){let r=n.parent;for(;r&&r.parent;)mn(r.parent.vnode)&&Tc(s,t,n,r),r=r.parent}}function Tc(e,t,n,s){const r=rs(t,e,s,!0);yn(()=>{Ys(s[t],r)},n)}function rs(e,t,n=ye,s=!1){if(n){const r=n[e]||(n[e]=[]),i=t.__weh||(t.__weh=(...o)=>{ze();const l=vn(n),c=$e(t,n,e,o);return l(),Qe(),c});return s?r.unshift(i):r.push(i),i}}const lt=e=>(t,n=ye)=>{(!kt||e==="sp")&&rs(e,(...s)=>t(...s),n)},Ec=lt("bm"),Wt=lt("m"),xc=lt("bu"),Cc=lt("u"),io=lt("bum"),yn=lt("um"),Ac=lt("sp"),Rc=lt("rtg"),Mc=lt("rtc");function Oc(e,t=ye){rs("ec",e,t)}const oo="components";function Zu(e,t){return co(oo,e,!0,t)||e}const lo=Symbol.for("v-ndc");function ef(e){return ce(e)?co(oo,e,!1)||e:e||lo}function co(e,t,n=!0,s=!1){const r Line truncated
* @vue/runtime-dom v3.5.39
* (c) 2018-present Yuxi (Evan) You and Vue contributors
* @license MIT
**/let Gs;const Ur=typeof window<"u"&&window.trustedTypes;if(Ur)try{Gs=Ur.createPolicy("vue",{createHTML:e=>e})}catch{}const $o=Gs?e=>Gs.createHTML(e):e=>e,ga="http://www.w3.org/2000/svg",ma="http://www.w3.org/1998/Math/MathML",tt=typeof document<"u"?document:null,Br=tt&&tt.createElement("template"),ya={insert:(e,t,n)=>{t.insertBefore(e,n||null)},remove:e=>{const t=e.parentNode;t&&t.removeChild(e)},createElement:(e,t,n,s)=>{const r=t==="svg"?tt.createElementNS(ga,e):t==="mathml"?tt.createElementNS(ma,e):n?tt.createElement(e,{is:n}):tt.createElement(e);return e==="select"&&s&&s.multiple!=null&&r.setAttribute("multiple",s.multiple),r},createText:e=>tt.createTextNode(e),createComment:e=>tt.createComment(e),setText:(e,t)=>{e.nodeValue=t},setElementText:(e,t)=>{e.textContent=t},parentNode:e=>e.parentNode,nextSibling:e=>e.nextSibling,querySelector:e=>tt.querySelector(e),setScopeId(e,t){e.setAttribute(t,"")},insertStaticContent(e,t,n,s,r,i){const o=n?n.previousSibling:t.lastChild;if(r&&(r===i||r.nextSibling))for(;t.insertBefore(r.cloneNode(!0),n),!(r===i||!(r=r.nextSibling)););else{Br.innerHTML=$o(s==="svg"?`<svg>${e}</svg>`:s==="mathml"?`<math>${e}</math>`:e);const l=Br.content;if(s==="svg"||s==="mathml"){const c=l.firstChild;for(;c.firstChild;)l.appendChild(c.firstChild);l.removeChild(c)}t.insertBefore(l,n)}return[o?o.nextSibling:t.firstChild,n?n.previousSibling:t.lastChild]}},ct="transition",Gt="animation",fn=Symbol("_vtc"),jo={name:String,type:String,css:{type:Boolean,default:!0},duration:[String,Number,Object],enterFromClass:String,enterActiveClass:String,enterToClass:String,appearFromClass:String,appearActiveClass:String,appearToClass:String,leaveFromClass:String,leaveActiveClass:String,leaveToClass:String},va=ge({},Zi,jo),_a=e=>(e.displayName="Transition",e.props=va,e),cf=_a((e,{slots:t})=>qs(dc,ba(e),t)),mt=(e,t=[])=>{B(e)?e.forEach(n=>n(...t)):e&&e(...t)},Kr=e=>e?B(e)?e.some(t=>t.length>1):e.length>1:!1;function ba(e){const t={};for(const w in e)w in jo||(t[w]=e[w]);if(e.css===!1)return t;const{name:n="v",type:s,duration:r,enterFromClass:i=`${n}-enter-from`,enterActiveClass:o=`${n}-enter-active`,enterToClass:l=`${n}-enter-to`,appearFromClass:c=i,appearActiveClass:u=o,appearToClass:a=l,leaveFromClass:d=`${n}-leave-from`,leaveActiveClass:m=`${n}-leave-active`,leaveToClass:_=`${n}-leave-to`}=e,b=wa(r),y=b&&b[0],F=b&&b[1],{onBeforeEnter:O,onEnter:P,onEnterCancelled:p,onLeave:g,onLeaveCancelled:R,onBeforeAppear:V=O,onAppear:S=P,onAppearCancelled:j=p}=t,T=(w,D,G,te)=>{w._enterCancelled=te,yt(w,D?a:l),yt(w,D?u:o),G&&G()},H=(w,D)=>{w._isLeaving=!1,yt(w,d),yt(w,_),yt(w,m),D&&D()},A=w=>(D,G)=>{const te=w?S:P,W=()=>T(D,w,G);mt(te,[D,W]),qr(()=>{yt(D,w?c:i),et(D,w?a:l),Kr(te)||Gr(D,s,y,W)})};return ge(t,{onBeforeEnter(w){mt(O,[w]),et(w,i),et(w,o)},onBeforeAppear(w){mt(V,[w]),et(w,c),et(w,u)},onEnter:A(!1),onAppear:A(!0),onLeave(w,D){w._isLeaving=!0;const G=()=>H(w,D);et(w,d),w._enterCancelled?(et(w,m),Jr(w)):(Jr(w),et(w,m)),qr(()=>{w._isLeaving&&(yt(w,d),et(w,_),Kr(g)||Gr(w,s,F,G))}),mt(g,[w,G])},onEnterCancelled(w){T(w,!1,void 0,!0),mt(p,[w])},onAppearCancelled(w){T(w,!0,void 0,!0),mt(j,[w])},onLeaveCancelled(w){H(w),mt(R,[w])}})}function wa(e){if(e==null)return null;if(Q(e))return[_s(e.enter),_s(e.leave)];{const t=_s(e);return[t,t]}}function _s(e){return fl(e)}function et(e,t){t.split(/\s+/).forEach(n=>n&&e.classList.add(n)),(e[fn]||(e[fn]=new Set)).add(t)}function yt(e,t){t.split(/\s+/).forEach(s=>s&&e.classList.remove(s));const n=e[fn];n&&(n.delete(t),n.size||(e[fn]=void 0))}function qr(e){requestAnimationFrame(()=>{requestAnimationFrame(e)})}let Sa=0;function Gr(e,t,n,s){const r=e._endId=++Sa,i=()=>{r===e._endId&&s()};if(n!=null)return setTimeout(i,n);const{type:o,timeout:l,propCount:c}=Ta(e,t);if(!o)return s();const u=o+"end";let a=0;const d=()=>{e.removeEventListener(u,m),i()},m=_=>{_.target===e&&++a>=c&&d()};setTimeout(()=>{a<c&&d()},l+1),e.addEventListener(u,m)}function Ta(e,t){const n=window.getComputedStyle(e),s=b=>(n[b]||"").split(", "),r=s(`${ct}Delay`),i=s(`${ct}Duration`),o=Xr(r,i),l=s(`${Gt}Delay`),c=s(`${Gt}Duration`),u=Xr(l,c);let a=null,d=0,m=0;t===ct?o>0&&(a=ct,d=o,m=i.length):t===Gt?u>0&&(a=Gt,d=u,m=c.length):(d=Math.max(o,u),a=d>0?o>u?ct:Gt:null,m=a?a===ct?i.length:c.length:0);const _=a===ct&&/\b(?:transform|all)(?:,|$)/.test(s(`${ct}Property`).toString());return{type:a,timeout:d,propCount:m,hasTransform:_}}function Xr(e,t){for(;e.length<t.length;)e=e.concat(e);return Math.max(...t.map((n,s)=>Yr(n)+Yr(e[s])))}function Yr(e){return e==="auto"?0:Number(e.slice(0,-1).replace(",","."))*1e3}function Jr(e){return(e?e.ownerDocument:document).body.offsetHeight}function Ea(e,t,n){const s=e[fn];s&&(t=(t?[t,...s]:[...s]).join(" ")),t==null?e.removeAttribute("class"):n?e.setAttribute("class",t):e.className=t}const zr=Symbol("_vod"),xa=Symbol("_vsh"),Ca=Symbol(""),Aa=/(?:^|;)\s*display\s*:/;function Ra(e,t,n){const s=e.style,r=ce(n);let i=!1;if(n&&!r){if(t)if(ce(t))for(const o of t.split(";")){const l=o.sli Line truncated
-2
View File
@@ -1,2 +0,0 @@
const __vite__mapDeps=(i,m=__vite__mapDeps,d=(m.f||(m.f=["assets/chunks/VPLocalSearchBox.DW8jxpb0.js","assets/chunks/framework.BWuWLRhz.js"])))=>i.map(i=>d[i]);
import{d as p,c as u,r as c,n as N,o as s,a as j,t as M,b as _,w as h,T as ue,e as m,_ as g,u as Ce,i as He,f as Be,g as de,h as y,j as d,k as i,l as z,m as se,p as S,q as F,s as X,v as U,x as ve,y as fe,z as Ee,A as Fe,F as x,B as A,C as W,D as Y,E as k,G as $e,H as B,I as ye,J as Q,K as G,L as Z,M as De,N as Pe,O as ie,P as Le,Q as Ve,R as ee,S as Oe,U as Ge,V as Ue,W as Se,X as Te,Y as je,Z as ze,$ as We,a0 as Ke,a1 as qe}from"./framework.BWuWLRhz.js";const Re=p({__name:"VPBadge",props:{text:{},type:{default:"tip"}},setup(e){return(t,n)=>(s(),u("span",{class:N(["VPBadge",e.type])},[c(t.$slots,"default",{},()=>[j(M(e.text),1)])],2))}}),Je={key:0,class:"VPBackdrop"},Xe=p({__name:"VPBackdrop",props:{show:{type:Boolean}},setup(e){return(t,n)=>(s(),_(ue,{name:"fade"},{default:h(()=>[e.show?(s(),u("div",Je)):m("",!0)]),_:1}))}}),Ye=g(Xe,[["__scopeId","data-v-c7b1b92b"]]),L=Ce;function Qe(e,t){let n,a=!1;return()=>{n&&clearTimeout(n),a?n=setTimeout(e,t):(e(),(a=!0)&&setTimeout(()=>a=!1,t))}}function re(e){return e.startsWith("/")?e:`/${e}`}function he(e){const{pathname:t,search:n,hash:a,protocol:o}=new URL(e,"http://a.com");if(He(e)||e.startsWith("#")||!o.startsWith("http")||!Be(t))return e;const{site:r}=L(),l=t.endsWith("/")||t.endsWith(".html")?e:e.replace(/(?:(^\.+)\/)?.*$/,`$1${t.replace(/(\.md)?$/,r.value.cleanUrls?"":".html")}${n}${a}`);return de(l)}function q({correspondingLink:e=!1}={}){const{site:t,localeIndex:n,page:a,theme:o,hash:r}=L(),l=y(()=>{var f,$;return{label:(f=t.value.locales[n.value])==null?void 0:f.label,link:(($=t.value.locales[n.value])==null?void 0:$.link)||(n.value==="root"?"/":`/${n.value}/`)}});return{localeLinks:y(()=>Object.entries(t.value.locales).flatMap(([f,$])=>l.value.label===$.label?[]:{text:$.label,link:Ze($.link||(f==="root"?"/":`/${f}/`),o.value.i18nRouting!==!1&&e,a.value.relativePath.slice(l.value.link.length-1),!t.value.cleanUrls)+r.value})),currentLang:l}}function Ze(e,t,n,a){return t?e.replace(/\/$/,"")+re(n.replace(/(^|\/)index\.md$/,"$1").replace(/\.md$/,a?".html":"")):e}const et={class:"NotFound"},tt={class:"code"},nt={class:"title"},at={class:"quote"},ot={class:"action"},st=["href","aria-label"],it=p({__name:"NotFound",setup(e){const{theme:t}=L(),{currentLang:n}=q();return(a,o)=>{var r,l,v,f,$;return s(),u("div",et,[d("p",tt,M(((r=i(t).notFound)==null?void 0:r.code)??"404"),1),d("h1",nt,M(((l=i(t).notFound)==null?void 0:l.title)??"PAGE NOT FOUND"),1),o[0]||(o[0]=d("div",{class:"divider"},null,-1)),d("blockquote",at,M(((v=i(t).notFound)==null?void 0:v.quote)??"But if you don't change your direction, and if you keep looking, you may end up where you are heading."),1),d("div",ot,[d("a",{class:"link",href:i(de)(i(n).link),"aria-label":((f=i(t).notFound)==null?void 0:f.linkLabel)??"go to home"},M((($=i(t).notFound)==null?void 0:$.linkText)??"Take me home"),9,st)])])}}}),rt=g(it,[["__scopeId","data-v-5dee7004"]]);function Ne(e,t){if(Array.isArray(e))return R(e);if(e==null)return[];t=re(t);const n=Object.keys(e).sort((o,r)=>r.split("/").length-o.split("/").length).find(o=>t.startsWith(re(o))),a=n?e[n]:[];return Array.isArray(a)?R(a):R(a.items,a.base)}function lt(e){const t=[];let n=0;for(const a in e){const o=e[a];if(o.items){n=t.push(o);continue}t[n]||t.push({items:[]}),t[n].items.push(o)}return t}function ct(e){const t=[];function n(a){for(const o of a)o.text&&o.link&&t.push({text:o.text,link:o.link,docFooterText:o.docFooterText}),o.items&&n(o.items)}return n(e),t}function le(e,t){return Array.isArray(t)?t.some(n=>le(e,n)):z(e,t.link)?!0:t.items?le(e,t.items):!1}function R(e,t){return[...e].map(n=>{const a={...n},o=a.base||t;return o&&a.link&&(a.link=o+a.link),a.items&&(a.items=R(a.items,o)),a})}function D(){const{frontmatter:e,page:t,theme:n}=L(),a=se("(min-width: 960px)"),o=S(!1),r=y(()=>{const w=n.value.sidebar,C=t.value.relativePath;return w?Ne(w,C):[]}),l=S(r.value);F(r,(w,C)=>{JSON.stringify(w)!==JSON.stringify(C)&&(l.value=r.value)});const v=y(()=>e.value.sidebar!==!1&&l.value.length>0&&e.value.layout!=="home"),f=y(()=>$?e.value.aside==null?n.value.aside==="left":e.value.aside==="left":!1),$=y(()=>e.value.layout==="home"?!1:e.value.aside!=null?!!e.value.aside:n.value.aside!==!1),V=y(()=>v.value&&a.value),b=y(()=>v.value?lt(l.value):[]);function P(){o.value=!0}function T(){o.value=!1}function I(){o.value?T():P()}return{isOpen:o,sidebar:l,sidebarGroups:b,hasSidebar:v,hasAside:$,leftAside:f,isSidebarEnabled:V,open:P,close:T,toggle:I}}function ut(e,t){let n;X(()=>{n=e.value?document.activeElement:void 0}),U(()=>{window.addEventListener("keyup",a)}),ve(()=>{window.removeEventListener("keyup",a)});function a(o){o.key==="Escape"&&e.value&&(t(),n==null||n.focus())}}function dt(e){const{page:t,hash:n}=L(),a=S(!1),o=y(()=>e.value.collapsed!=null),r=y(()=>!!e.value.link),l=S(!1),v=()=>{l.value=z(t.value.relativePath,e.value.link)};F([t,e,n],v),U(v);const f=y(()=>l.value?!0:e.value.items?le(t.value.relativePath,e.value.items):!1),$=y(()=>!!(e.value.items&&e.value.items.lenLine truncated
-1
View File
@@ -1 +0,0 @@
import{_ as e,o as t,c as a}from"./chunks/framework.BWuWLRhz.js";const m=JSON.parse('{"title":"","description":"","frontmatter":{"layout":"home","hero":{"name":"Archie","text":"Personal agent platform","tagline":"Durable agents, conversations, workflows, tools, and integrations.","image":{"src":"/favicon.svg","alt":"Archie"},"actions":[{"theme":"brand","text":"Architecture","link":"/architecture/"}]},"features":[{"title":"Personal agents","details":"Persistent assistants with their own identity, specialisation, and private memory."},{"title":"Conversations","details":"Durable, branchable conversations across messaging channels."},{"title":"Workflows","details":"Reusable, versioned behaviour definitions for structured and automated work."},{"title":"Extensible capabilities","details":"Typed plugins, tools, channels, and infrastructure integrations."}]},"headers":[],"relativePath":"index.md","filePath":"index.md","lastUpdated":null}'),s={name:"index.md"};function n(i,r,o,l,c,d){return t(),a("div")}const p=e(s,[["render",n]]);export{m as __pageData,p as default};
-1
View File
@@ -1 +0,0 @@
import{_ as e,o as t,c as a}from"./chunks/framework.BWuWLRhz.js";const m=JSON.parse('{"title":"","description":"","frontmatter":{"layout":"home","hero":{"name":"Archie","text":"Personal agent platform","tagline":"Durable agents, conversations, workflows, tools, and integrations.","image":{"src":"/favicon.svg","alt":"Archie"},"actions":[{"theme":"brand","text":"Architecture","link":"/architecture/"}]},"features":[{"title":"Personal agents","details":"Persistent assistants with their own identity, specialisation, and private memory."},{"title":"Conversations","details":"Durable, branchable conversations across messaging channels."},{"title":"Workflows","details":"Reusable, versioned behaviour definitions for structured and automated work."},{"title":"Extensible capabilities","details":"Typed plugins, tools, channels, and infrastructure integrations."}]},"headers":[],"relativePath":"index.md","filePath":"index.md","lastUpdated":null}'),s={name:"index.md"};function n(i,r,o,l,c,d){return t(),a("div")}const p=e(s,[["render",n]]);export{m as __pageData,p as default};
Binary file not shown.
Binary file not shown.
Loaded 100 of 170 files, more files were not shown because too many files have changed in this diff. Show more