Eight approved decisions existed only as beads memories and were lost when
the tracker was removed. Recovered from a backup taken six minutes before
8bf0f6b and folded into the docs that own them, rather than a new document.
- migration-decisions: recorded position as of 2026-07-29, the deferred
private-input-DTO compromise, and the agreed internal/app/{archied,
agentworker} next step
- configuration: missing credential degrades a capability, only invalid
config is fatal; config generation moves from install.sh to archied setup
- identity: the three-layer invariants/SOUL/representation model, and why
a curator may only propose SOUL changes
- agent-system: the curator isolation invariant (curators are peers, never
on a chat turn's critical path)
- messaging-and-work-intake: semantic search over messages is an explicit
non-goal, with the measurements behind it
- safe-change-and-recovery: the /restart deadlock and lockout constraints
- plugins-and-extensions: dates the surprisal deferral
Also replaces the dead `**Beads issue:** archie-core-5d7` frontmatter across
all 12 documents with the GitHub issue it migrated to (#73), and rewrites
every other beads identifier to its issue number.
2.6 KiB
Repository Organisation
Status: Approved
Date: 2026-07-28
Tracking issue: #73
Target structure
Archie MUST be organised around cohesive application responsibilities:
cmd/
archied/
archie-agent/
internal/
domain/
<area>/
eventbus/
policy/
infrastructure/
configuration/
eventbus/
nats/
forge/
persistence/
<external-service>/
app/
archied/
agentworker/
plugins/
<plugin>/
deployments/
<supported-assembly>/
docs/
guides/
examples/
<copyable-example>/
extras/
<optional-extension>/
Domain names are chosen from application behaviour during package review. Existing names MUST NOT be retained merely to reduce migration work.
Domain areas
A domain owns one cohesive job performed by Archie. It contains that job's language, state, rules, operations, commands, events, policy implementations, runtime settings, and required service contracts.
Code that changes together SHOULD live together. Empty or ceremonial entities,
repositories, or services layers are prohibited.
Application composition
internal/app:
- constructs domains and infrastructure implementations;
- translates external configuration into domain and plugin settings;
- connects commands, events, and shared contracts;
- starts services in dependency order;
- owns health aggregation and shutdown ordering.
cmd/* parses only process-level input and invokes the relevant application
composition package. It MUST NOT contain substantive wiring or act as a service
locator.
Process boundaries
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.
Possible future extraction does not justify premature network protocols or duplicated service scaffolding.
Optional and operational material
extras/<extension>contains a maintained optional extension with real behaviour. Core Archie MUST NOT import it, and removingextras/MUST NOT prevent the core application from building or running.deployments/<assembly>contains a supported assembly, including deployment definitions and concise operational instructions.docs/guides/contains handwritten explanation and links to generated reference material.examples/contains copyable samples with explicit purpose, prerequisites, and support expectations.
Supported assemblies SHOULD demonstrate that capabilities can be selected independently.