Skip to content

ADR-0001: Record Architecture Decisions and Maintain Strict Repository Containment

Status

Accepted

Context

Swayrm is a platform and ecosystem for civic collaboration and grassroots governance. Designing and building this system requires collaboration between humans and various AI models (Gemini, Claude, GPT, etc.) across disparate environments, local workstations, and volatile cloud VM instances.

We face two critical risks:

  1. Loss of institutional knowledge due to environment volatility: Cloud VM nodes are disposable. Writing state or agent memory to user home directories outside the repository leads to immediate data loss upon VM recycling.
  2. Vendor lock-in and fragmentation: Tying agent memory or documentation to vendor-specific tooling (e.g. Gemini-only files, Claude-only configs) prevents seamless handoffs to other contributors or models. Furthermore, opaque agent memory violates the core ethos of Swayrm: transparency and verifiable collective reasoning.

Decision

  1. Architecture Decision Records (ADRs): We will use ADRs to document significant architectural, governance, and methodological decisions under docs/decisions/.
  2. Universal AI Protocol (AGENTS.md): All guidelines, ground rules, and domain context will be anchored in AGENTS.md. Tool-specific configurations (GEMINI.md, CLAUDE.md, .cursorrules) will act solely as thin forwarders to AGENTS.md.
  3. Strict Repository Containment: No tool or AI agent shall write or persist memory outside the repository root (./).
  4. Environment Portability: All file references and tooling must utilize relative paths (./...) and make zero assumptions regarding operating system, absolute file paths, or host usernames.
  5. Transparent Deliberation Log: Discussions, alternatives, and sparring dialogues will be captured in docs/deliberations/.

Consequences

Positive

  • Complete transparency: Any collaborator (human or AI) can audit the entire design rationale from day one.
  • Resilience: Zero data is lost when a VM node is discarded; everything lives in git.
  • Interoperability: Seamless switching between different AI models and tools without loss of context or drift.
  • Alignment with project ethics: An open civic collaboration platform practices total transparency in its own development.

Negative / Trade-offs

  • AI agents cannot rely on silent background memory files and must explicitly update tracked Markdown documents within the repository.